api-contract-versioning

api-contract-versioning

Core rule: API contracts are owned by packages/shared and consumed by the server and both clients. Changing a shared type or Zod schema is a cross-cutting change — validate all consumers before merging.

When to use this skill

• Adding, removing, or renaming a field in a shared API request/response type
• Creating a new Zod validation schema for a route payload
• Modifying an existing schema exported from packages/shared/src/schema.ts
• Changing packages/shared/src/api.ts DTOs or the ApiTransport contract
• Adding a new API endpoint that both mini-program and web will call
• Reviewing whether a server route's response shape matches the client's expectation

When NOT to use this skill

• Task is purely about internal server business logic with no exposed contract change
• Task is only about a client-local UI type that never crosses the network
• Task is about database schema evolution without API surface impact (use database-migration-safety)
• Task is about adding a new route file or domain decomposition (use server-domain-architecture)

Shared contract layers

JoyJoin API contracts live in three layers inside packages/shared:

Layer	Location	Purpose
Database + Zod schemas	packages/shared/src/schema.ts	Drizzle tables + runtime validation
API DTOs + transport	packages/shared/src/api.ts (barrel) and packages/shared/src/api/*.ts	TypeScript types, transport contract, domain modules
Domain types	packages/shared/src/types/*.ts	Cross-cutting domain types

Versioning: The server strips /api/v1/ prefixes and routes identically to /api/*. There is no active breaking-version negotiation. Prefer additive fields with feature detection over version bumps.

For implementation details — Zod/Drizzle examples, DTO patterns, drift detection, and cross-platform consumption — see references/implementation.md.

Quick examples

User says: "I need to add a new field dietaryNotes to the event pool registration payload." Apply this skill by:

1. Add the column to eventPools in packages/shared/src/schema.ts (if persisted)
2. Update insertEventPoolRegistrationSchema in the same file
3. Add dietaryNotes?: string[] | null to EventPoolRegistrationPayload in packages/shared/src/api/eventPools.ts (re-exported through packages/shared/src/api.ts)
4. Run npm run typecheck across @joyjoin/server, @joyjoin/user-client, and mini-program Result: The contract is updated in one place and all consumers type-check together.

---

User says: "The server is returning a new themeEmoji field but the mini-program isn't seeing it." Apply this skill by: Checking packages/shared/src/api/eventPools.ts for PoolGroupSummary — if themeEmoji is missing from the interface, add it there and re-export it through packages/shared/src/api.ts. Also verify apps/mini-program/src/lib/api/api.ts imports the updated type via @shared/api. Result: Type drift is caught at the shared boundary, not at runtime in the client.

Troubleshooting

• Type mismatch between server and client after schema change — Run npm run typecheck across all workspaces. Fix packages/shared/src/api.ts or schema.ts before checking consumers.
• Zod validation rejects a payload that looks correct — Check whether the schema uses .strict(), .omit(), or .extend() in a way that forbids the field.
• Client sees unknown for an API response field — The field is likely not declared in the relevant packages/shared/src/api/<domain>.ts module (re-exported through packages/shared/src/api.ts). Add it there and re-export from packages/shared/src/index.ts if needed.
• Adding a required field to a response breaks an older client — Make the field optional (?:) in the shared DTO first, then migrate clients before making it required.

Review checklist

• Zod schema changes in schema.ts are reflected in all server safeParse consumers
• New or changed response fields are added to the corresponding interface in packages/shared/src/api/<domain>.ts (and re-exported through packages/shared/src/api.ts)
• Both web and mini-program clients import the updated type from @shared/api
• No duplicate local types were created when a shared type already exists
• Additive changes use optional fields (?:) before making them required across all surfaces
• npm run typecheck passes for @joyjoin/server, @joyjoin/user-client, and mini-program