naming-conventions.mdx

title	Naming Conventions
description	Standardized naming rules for ObjectStack Protocol schemas and configurations

Naming Conventions

Standardized naming rules for ObjectStack Protocol schemas and configurations

Overview

ObjectStack uses two distinct naming conventions depending on the context:

• Configuration Keys (TypeScript properties): camelCase
• Machine Names (Data identifiers): snake_case

This dual-convention approach aligns with industry best practices from Salesforce, ServiceNow, and Kubernetes.

Configuration Keys (camelCase)

When to Use

Use camelCase for all TypeScript property names in schema definitions:

• Schema property keys
• Function parameters
• Object configuration options
• API request/response fields (at the protocol level)

Examples

// ✅ Correct
export const FieldSchema = z.object({
  maxLength: z.number().optional(),
  minLength: z.number().optional(),
  defaultValue: z.any().optional(),
  referenceFilters: z.array(z.string()).optional(),
  isRequired: z.boolean().default(false),
  isUnique: z.boolean().default(false),
});

Rationale

• TypeScript Convention: Matches TypeScript/JavaScript ecosystem standards
• Developer Experience: Familiar to frontend and backend developers
• IDE Support: Better autocomplete and type inference
• Industry Alignment: Matches REST API conventions (JSON payloads)

Machine Names (snake_case)

When to Use

Use snake_case for all data identifiers that represent database or system entities:

• Object names (e.g., project_task, customer_account)
• Field names (e.g., first_name, email_address)
• Workflow names, Report names
• Any identifier stored as data

Examples

// ✅ Correct - Machine names in snake_case
const field = {
  name: 'first_name',         // Data identifier - snake_case
  label: 'First Name',        // Display text - Title Case
  type: 'text',              // Enum value - lowercase
  maxLength: 50,             // Config property - camelCase
};

Summary

Context	Convention	Example
Configuration Keys	camelCase	maxLength, isRequired, defaultValue
Machine Names	snake_case	customer_account, first_name
Display Text	Title Case	Customer Account, First Name
Enum Values	lowercase	text, number, date
Constants	UPPER_SNAKE_CASE	MAX_LENGTH, DEFAULT_TIMEOUT

For complete details and validation patterns, see CONTRIBUTING.md.