naming-conventions.md

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.