Skip to main content

Source: ocean/docs/adr/ADR-036-unified-field-naming-convention.md | ✏️ Edit on GitHub

ADR-036: Unified Field Naming Convention

Status​

Proposed

Context​

The Ocean platform currently has inconsistent field naming between layers:

  • Database: snake_case (e.g., stripe_customer_id, member_role)
  • GraphQL API: camelCase (e.g., stripeCustomerId, memberRole)
  • Frontend: Mixed usage with transformation functions

This inconsistency leads to:

  1. Complex transformation logic in multiple places
  2. Increased cognitive load for developers
  3. Potential bugs from incorrect field mapping
  4. Duplicated type definitions

Decision​

We will adopt a snake_case-first approach throughout the entire stack:

  1. Database: Continue using snake_case (PostgreSQL convention)
  2. GraphQL API: Use snake_case for all fields
  3. Frontend: Use snake_case directly from API responses
  4. Generated Types: Single source of truth from database schema

Implementation Strategy​

  1. Update GraphQL schema to use snake_case fields
  2. Remove all transformation functions
  3. Update frontend to use snake_case consistently
  4. Regenerate GraphQL types with snake_case

Consequences​

Positive​

  • Single naming convention across all layers
  • No transformation logic needed
  • Simpler type definitions
  • Direct mapping from database to frontend
  • Reduced code complexity

Negative​

  • Breaking change for existing API consumers (mitigated by being pre-launch)
  • Goes against GraphQL convention of camelCase
  • May look unusual in JavaScript/TypeScript code

Mitigation​

  • Since we're pre-launch, breaking changes are acceptable
  • Modern TypeScript handles snake_case well
  • ESLint rules can be adjusted to allow snake_case

Implementation Plan​

  1. Update GraphQL schema.ts to use snake_case
  2. Update resolvers to return fields directly without transformation
  3. Remove transformation functions from hooks
  4. Update frontend components to use snake_case fields
  5. Regenerate all types