Schema matches implementation

A stale schema is worse than no schema: it actively misleads consumers and downstream tooling. When openapi.yaml documents 8 endpoints but 12 exist in code, SDK generators produce incomplete clients, contract tests pass against a fiction, and third-party integrators build on fields that have already changed. iso-25010:2011 compatibility.interoperability fails in the most damaging way — the schema signals reliability it does not deliver. Drift compounds silently with every schema-less code change.

Eliminate schema drift by generating the spec from code rather than maintaining it manually. Use Zod schemas as the single source of truth for both validation and OpenAPI output:

// Zod schema validates requests AND generates OpenAPI spec:
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
})
// Same object drives runtime validation and schema export

If you maintain the spec manually, add a CI step using openapi-diff or spectral that fails the build when the spec does not match the implementation. Run it on every pull request.