How would you stop published OpenAPI documents from drifting away from the running services?

## Why drift happens A published document is accurate on the day it is written. It decays because the *cost of updating it* and the *cost of not updating it* are paid by different people at different times. A developer adds a field; nothing breaks; the spec is now slightly wrong. Multiply by a hundred changes and the document becomes something consumers have learned not to trust — at which point they read the code or ask in chat, and the spec stops being maintained at all. So the design goal is not diligence. It is arranging things so that a divergence is *detected automatically* and, ideally, cannot be introduced in the first place. ## Level 1 — eliminate the second source of truth Drift requires two artefacts that can disagree. Collapse them. If the contract is authoritative, generate server interfaces from it and have the implementation implement them. A change on either side that breaks agreement is then a compile error — the strongest, cheapest, earliest signal available. Its limit is that it constrains shapes and routes, not semantics: nothing stops a handler returning an empty list where the contract implies a populated one. If the code is authoritative, generate the document from it, **commit the generated file**, and have CI regenerate and fail on any difference. The document then cannot be stale by construction, and every contract change surfaces as a diff in code review — which also fixes the quieter problem that code-first APIs change without anyone reviewing the change. Anything else — a hand-written spec beside a hand-written implementation, with goodwill in between — will drift. ## Level 2 — publish from the pipeline A manual publication step is a drift source of its own: the repository is right and the developer portal is six months old. Publish as part of deployment, from the same commit, and record which build the published document came from. Two useful properties fall out: the portal can never be ahead of or behind production by more than a deploy, and "which version of the contract is live in this environment" becomes an answerable question. ## Level 3 — verify against the running service Static agreement between a spec and the code that generated it is not agreement with observed behaviour. Two complementary checks: - **Contract tests through a generated client.** Drive the service in a test environment using the SDK generated from the published document. Deserialisation failures, missing fields and unexpected nullability show up as test failures, and you exercise exactly the code path consumers use. - **Response validation.** In test environments, validate real responses against the declared schemas. This catches the cases a generator cannot see — a field that is documented as required but sometimes absent, an enum that has grown a value the spec does not list, an error shape that does not match the declared envelope. These are the only mechanisms that catch semantic drift, and they are worth the cost on APIs with external consumers. ## Level 4 — gate on comparison, not just on validity A spec can be perfectly fresh and still ruin someone's week. Diff each candidate document against the last published one and classify the change; tools such as oasdiff exist for exactly this. Breaking changes should require an explicit, recorded decision rather than being discovered by a consumer. Additive changes can flow through automatically. This turns "did anyone think about compatibility" from a review habit into a pipeline state. ## Level 5 — make ownership and staleness visible At fleet scale the technical controls need an organisational frame: - A **catalogue** listing every service's published document, its owning team and the deploy it came from. Without it, nobody can even enumerate what exists. - **Required checks** — lint, diff, contract tests — configured centrally so a new repository inherits them rather than opting in. - **A staleness signal** that is visible to the owning team: a document whose last publication predates the service's last deploy is suspect by definition, and that comparison is trivially automatable. - **Clear ownership of the shared machinery** — the ruleset, the generation tooling, the publication path — because a pipeline nobody owns degrades quietly. ## What to accept Perfect fidelity is not the target; cost-effective detection is. Descriptions and examples will always lag reality somewhat, and chasing that with process is a poor trade. Concentrate enforcement on the parts consumers' code depends on — routes, status codes, field names, types, nullability, enum values, error shapes — and let prose be improved opportunistically. The measure of success is not that no document is ever wrong, but that a wrong one is found by a pipeline rather than by a consumer.