# 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. ## 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 3.2 is generated. Nothing in this repository checks it any more. `OpenApi32CompatibilityReport` and `OpenApiToolchainMatrix` — the promotion report that hashed the snapshot and recorded which parser, linter, generator and client compile had read the 3.2 output — were removed on 2026-09-25: they lived in production code and only their own tests called them. A service that generates 3.2 with `WebOpenApi32Generator` (library, `adapter:inbound:web-advanced`) owns that check in its own build. Promotion stays a judgement, recorded in `docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md`. ## Running it No workflow in this repository generates 3.2. `OpenApiVersionLane.STABLE_3_1` is the release artifact; `WebOpenApi32GeneratorTest` covers the generator.