openapi-contract

Keep the OpenAPI contract true

An API document that is not generated from, or checked against, the running code is fiction within a month. Keep it precise, prove the implementation matches it in tests, and treat drift or an unannounced breaking change as a failing build. Sources: OpenAPI Specification 3.1.x (3.2.0 published September 2025), JSON Schema 2020-12, RFC 9457 (problem details), RFC 9110 (HTTP semantics).

Steps

1. Find how the repo produces its contract. Generated from route schemas (best: zod/pydantic/JSON Schema rendered to OpenAPI), hand-maintained and checked by a test, or absent. Call search_lore for the convention and the check command (in the factory itself: node scripts/openapi.mjs --check). Never hand-edit a generated document; fix the source and regenerate.
2. Respect the document's version. Write for the openapi: version the repo declares; do not bump it unless every consumer tool supports the new one. In 3.1, schemas are full JSON Schema 2020-12: use type: [string, "null"] not nullable, numeric exclusiveMinimum, examples (array) in schemas, and the top-level webhooks map for outbound events. 3.0 documents keep 3.0 idioms.
3. Define the schemas where the route validates. The same schema object validates input at the boundary and renders the contract, so they cannot disagree. Every field typed; required stated; formats declared (uuid, date-time, email); enums closed; string lengths and array sizes bounded; readOnly/writeOnly for server-set and secret fields. Request bodies reject unknown properties (additionalProperties: false) where the repo validates strictly; response schemas document every field the server emits.
4. Document every response, errors included. Success status and body; each error status with the repo's error envelope (RFC 9457 application/problem+json if the repo uses it) and its machine codes; 401/403 where auth applies; 422/400 for validation; 429 with rate-limit headers when limited (the rate-limiting skill); the pagination envelope and parameters for lists (the pagination-and-filtering skill); Idempotency-Key where accepted.
5. Name, tag and secure operations. Unique operationId consistent with siblings (listTickets, createTicket), a one-sentence summary, tags, and a security requirement per operation (or the global default, stated) so a reviewer can audit authorisation from the document alone. In the factory's own API every endpoint in packages/dispatch/src/api/openapi/spec.ts declares its capability tier (public / read / full); set it for each new route.
6. Regenerate, lint, and diff for breaks. Run the generator; lint with the repo's linter only if it is already installed (npx --no-install @redocly/cli lint, npx --no-install @stoplight/spectral-cli lint); never fetch one. Compare with the base branch without writing a file outside the worktree (the safety hook blocks that): oasdiff breaking <(git show <base>:<path>) <path> if oasdiff is installed, otherwise read git diff <base> -- <path>. Breaking: removing a path, operation, field or enum value from a response; adding a required request field; narrowing a type or constraint; changing a status code or auth. Any break is a versioning event (the api-versioning skill), not a doc update.
7. Prove the code matches the document. Run the repo's freshness check and its two-way route test (every documented path is routed; every routed path is documented). Validate real responses against the schema in integration tests (a response validator, or Schemathesis-style property tests if the repo has them), so a handler that returns an undocumented field or status fails. If the repo has no check, add the smallest one and name it in the evidence.
8. Regenerate derived clients and types in the same change and run their consumers' tests; a stale generated client is the same bug as a stale document.