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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Done when
The regenerated document is committed with the code, the freshness check and lint
pass, the break comparison is clean (or the break is versioned), response validation
covers the changed operations, and each acceptance criterion has evidence via the
record-evidence skill (document diff, check output, contract test run — the
contract-test skill).
Review checklist
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While regenerating the contract you learn where it lives, how it is produced and the check that keeps it honest in CI. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: openapi-contract3description: Use when a ticket adds or changes an HTTP API and the repo keeps (or should keep) a machine-readable contract — an OpenAPI/Swagger document, JSON Schemas, generated clients or types — that must stay in lockstep with the routes and be validated in CI. Invoke for "document the endpoint", "update the OpenAPI spec", "the generated client is out of date", or "add request/response schemas".4stack: [node, python, go, java, rust, csharp, kotlin, ruby]5area: backend6metadata:7 source: https://skillmd.com/skills/tmj-90/openapi-contract8---910# Keep the OpenAPI contract true1112An API document that is not generated from, or checked against, the running code is13fiction within a month. Keep it precise, prove the implementation matches it in tests,14and treat drift or an unannounced breaking change as a failing build. Sources: OpenAPI15Specification 3.1.x (3.2.0 published September 2025), JSON Schema 2020-12, RFC 945716(problem details), RFC 9110 (HTTP semantics).1718## Steps19201. **Find how the repo produces its contract.** Generated from route schemas (best:21 zod/pydantic/JSON Schema rendered to OpenAPI), hand-maintained and checked by a22 test, or absent. Call `search_lore` for the convention and the check command (in23 the factory itself: `node scripts/openapi.mjs --check`). Never hand-edit a generated24 document; fix the source and regenerate.252. **Respect the document's version.** Write for the `openapi:` version the repo26 declares; do not bump it unless every consumer tool supports the new one. In 3.1,27 schemas are full JSON Schema 2020-12: use `type: [string, "null"]` not `nullable`,28 numeric `exclusiveMinimum`, `examples` (array) in schemas, and the top-level29 `webhooks` map for outbound events. 3.0 documents keep 3.0 idioms.303. **Define the schemas where the route validates.** The same schema object validates31 input at the boundary and renders the contract, so they cannot disagree. Every field32 typed; `required` stated; formats declared (`uuid`, `date-time`, `email`); enums33 closed; string lengths and array sizes bounded; `readOnly`/`writeOnly` for34 server-set and secret fields. Request bodies reject unknown properties35 (`additionalProperties: false`) where the repo validates strictly; response schemas36 document every field the server emits.374. **Document every response, errors included.** Success status and body; each error38 status with the repo's error envelope (RFC 9457 `application/problem+json` if the39 repo uses it) and its machine codes; `401/403` where auth applies; `422`/`400` for40 validation; `429` with rate-limit headers when limited (the `rate-limiting` skill);41 the pagination envelope and parameters for lists (the `pagination-and-filtering`42 skill); `Idempotency-Key` where accepted.435. **Name, tag and secure operations.** Unique `operationId` consistent with siblings44 (`listTickets`, `createTicket`), a one-sentence summary, tags, and a `security`45 requirement per operation (or the global default, stated) so a reviewer can audit46 authorisation from the document alone. In the factory's own API every endpoint in47 `packages/dispatch/src/api/openapi/spec.ts` declares its capability tier48 (`public` / `read` / `full`); set it for each new route.496. **Regenerate, lint, and diff for breaks.** Run the generator; lint with the repo's50 linter only if it is already installed (`npx --no-install @redocly/cli lint`,51 `npx --no-install @stoplight/spectral-cli lint`); never fetch one.52 Compare with the base branch without writing a file outside the worktree (the safety53 hook blocks that): `oasdiff breaking <(git show <base>:<path>) <path>` if oasdiff is54 installed, otherwise read `git diff <base> -- <path>`. Breaking:55 removing a path, operation, field or enum value from a response; adding a required56 request field; narrowing a type or constraint; changing a status code or auth. Any57 break is a versioning event (the `api-versioning` skill), not a doc update.587. **Prove the code matches the document.** Run the repo's freshness check and its59 two-way route test (every documented path is routed; every routed path is60 documented). Validate real responses against the schema in integration tests (a61 response validator, or Schemathesis-style property tests if the repo has them), so62 a handler that returns an undocumented field or status fails. If the repo has no63 check, add the smallest one and name it in the evidence.648. **Regenerate derived clients and types** in the same change and run their65 consumers' tests; a stale generated client is the same bug as a stale document.6667## Done when6869The regenerated document is committed with the code, the freshness check and lint70pass, the break comparison is clean (or the break is versioned), response validation71covers the changed operations, and each acceptance criterion has evidence via the72`record-evidence` skill (document diff, check output, contract test run — the73`contract-test` skill).7475## Review checklist7677- [ ] One source of truth; no hand-edited generated file.78- [ ] Every new or changed operation has typed, bounded request and response schemas.79- [ ] Every response documented, errors and `429` included, in the repo's envelope.80- [ ] `operationId` unique; `security` stated per operation.81- [ ] No unversioned breaking change against the base branch.82- [ ] Tests validate actual responses against the document; freshness check green.8384## Capture lore8586This skill is one of the places durable, reusable knowledge naturally surfaces:87**While regenerating the contract you learn where it lives, how it is produced and the check that keeps it honest in CI.** That kind of fact is *lore*. Capture it via the **lore-capture88protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):89call the Memory MCP `suggest_lore` once at the close of your work — reusable90conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.