ring:designing-data-model

Data Modeling — Producing the Stack-Native Schema

When to use

• OpenAPI spec passed Gate 4 validation (or Gate 4 SKIPPED for features with no API surface)
• System stores persistent data
• Large Track workflow (2+ day features)

Skip when

• Small Track workflow → skip to ring:writing-plans
• No persistent data → skip to Dependency Map
• OpenAPI spec not validated (and Gate 4 not SKIPPED) → complete Gate 4 first

Sequence

Runs before: ring:pinning-dependency-versions Runs after: ring:designing-api-contracts

The deliverable is a REAL, stack-native schema file — DDL that becomes migrations, not markdown tables. The DDL IS the deliverable: CREATE TABLE, indexes, and constraints are required, not forbidden.

Phase 0: Database Field Naming Strategy (MANDATORY)

See shared-patterns/standards-discovery.md for the complete workflow.

Step 1: Check for Gate 4 API standards

If docs/pre-dev/{feature}/api-standards-ref.md exists, auto-detect naming convention.

Step 2: Ask user

If api-standards-ref.md EXISTS: AskUserQuestion: "How should database fields be named?"

• "Convert to snake_case (Recommended)" — API: userId → DB: user_id
• "Keep same as API (camelCase)" — API: userId → DB: userId
• "Different standards — provide DB dictionary"
• "Define manually"

If api-standards-ref.md DOES NOT EXIST: AskUserQuestion: "How should database fields be named?"

• "Use snake_case (Recommended)" — standard for PostgreSQL/MySQL
• "Use camelCase" — standard for MongoDB/document DBs
• "Load from standards document"
• "Define manually"

Step 3: Generate db-standards-ref.md

Option: Convert to snake_case — apply automatic rules:

• userId → user_id, createdAt → created_at, isActive → is_active, phoneNumber → phone_number, userID → user_id

Option: Keep same — copy field names without modification.

Option: Load from doc — WebFetch or read, extract field definitions, save to db-standards-ref.md.