2.4 KiB
OpenAPI 3.2: the experimental lane
Why it is a lane rather than an upgrade
Generating 3.2 is cheap. Adopting it is not, and the two get conflated because the generated document looks fine.
The value of an API description is entirely in what consumes it. A document in a version a client generator does not fully understand does not fail — it produces a client that compiles and is wrong, which is worse than no document at all.
So 3.1.2 stays the release artifact and 3.2 is generated beside it, with a report.
The invariant
Generating 3.2 must not change the 3.1 snapshot. Both come from the same model, so a contributor that mutates it on the way to 3.2 changes the artifact that is actually shipped — silently, and only when the experimental lane runs.
OpenApi32CompatibilityReport hashes the snapshot before and after, and a difference is a promotion
blocker with its own message.
The toolchain matrix
Four kinds of tool, checked separately, because passing one says nothing about the others:
| Kind | What it catches | What it misses |
|---|---|---|
| Parser | Structural errors | Anything semantically odd |
| Linter | Style rule violations | Accepts documents a parser rejects |
| Generator | Unsupported constructs — sometimes | Usually emits a wrong-but-valid signature instead of failing |
| Client compile | The wrong signature the generator emitted | Runtime behaviour |
OpenApiToolchainMatrix.complete() requires at least one passing tool of each kind.
gaps() names the kinds that have none.
"OpenAPI 3.2 works" is not a statement anybody can make. "This document is read correctly by these four tools at these versions" is.
Streaming descriptions
The substantive difference between 3.1 and 3.2 for this application is how streaming responses are described. Those differences are reported separately rather than folded into a pass/fail, because a green pass hides what changed.
Promotion
promotionBlockers(adrAccepted) always includes the ADR blocker until one is accepted, however
green the matrix is. A machine-checkable matrix cannot decide whether the consumer population is
ready; that is a judgement, and it belongs in
docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md.
Running it
The experimental generation runs in its own workflow and publishes the 3.2 document and the compatibility report as artifacts. It never runs in the release workflow, so the release artifact cannot depend on whether it ran.