Evaluate OpenAPI 3.2 support

[benjamineckstein]

The openapi.tools directory (we are listed since apisyouwonthate/openapi.tools#776) tracks OAS 3.2 support per tool, and our entry currently shows 3.2 as unsupported. Spotted while reviewing the listing diff.

Scope to evaluate:

• What 3.2 changes relative to 3.1 that affects us (new keywords, semantics changes, anything touching schemas, parameters, discriminators)
• Whether the parser dependency (devizzent/cebe-php-openapi) accepts 3.2 documents at all, and what our structural-rejection guard does with a 3.2 version string
• Corpus: add at least one real 3.2 spec as a fixture once available
• Update the supported-version matrix docs (1.0.0: state the supported OpenAPI version matrix explicitly #42 follow-up) either way: explicitly supported or explicitly rejected with a clear error

Win condition: either real 3.2 support with corpus coverage, or a documented, deliberate rejection. Bonus: openapi.tools entries carry an "oas-v32-early" badge for early adopters, worth having when we update our listing.

[benjamineckstein]

OpenAPI 3.2 research findings

Status

OpenAPI 3.2.0 is released, not a draft. Published 2025-09-19, announced 2025-09-23. Official version string: 3.2.0 (no 3.2.x patch release exists yet). Authoritative spec: https://spec.openapis.org/oas/v3.2.0.html, changelog and migration guide: https://learn.openapis.org/upgrading/v3.1-to-v3.2.html, announcement: https://www.openapis.org/blog/2025/09/23/announcing-openapi-v3-2. Fully backward compatible with 3.1: every valid 3.1 document is a valid 3.2 document after bumping the version string. No JSON Schema dialect change, still 2020-12.

Generator-relevant delta, 3.1 -> 3.2

Feature	What it is	Affects us	Effort
query HTTP method	New first-class operation on Path Item	Yes: routes + controllers. cebe's PathItem drops it, so the operation vanishes silently. Laravel has no Route::query(), would need Route::match(['QUERY'], ...) or addRoute	M
additionalOperations	Map of arbitrary HTTP verbs to Operations	Yes, same layer as query, currently dropped silently	M
in: querystring parameter	Whole query string as one Schema	Yes if used: parameter-level rules generation would miss it. Rare in the wild	M
Discriminator defaultMapping	Fallback schema when discriminator value unmapped	Yes: our morphable base (issue #38) could map it to a default morph. Optional propertyName also new	S/M
itemSchema + streaming media types (SSE, JSON Lines, json-seq, multipart)	Per-item schema for streamed bodies	Partially: we could emit the item Data class and leave transport to the user. Graceful degrade is acceptable v1	M/L
components.mediaTypes	Reusable Media Type Objects	Yes if used: refs into it would not resolve through cebe today	M
$self	Canonical document URI for multi-doc composition	Mostly ignorable for us (single-doc input), must just not crash	S
Tags: summary, parent, kind	Tag taxonomy/hierarchy	Mostly ignorable: we only use tag names for controller grouping. Must tolerate the fields	S
Example Object dataValue/serializedValue	Richer examples	Ignorable, we do not consume examples	S
Server name, response summary, response description now optional	Metadata loosening	Ignorable, just tolerate	S
OAuth: device flow, oauth2MetadataUrl, deprecated security schemes	Security metadata	Ignorable, we do not generate auth code	S
XML nodeType	XML mapping	Ignorable, JSON-only generator	S
propertyNames	JSON Schema 2020-12 keyword, already legal in 3.1	Not a 3.2 change. We do not enforce it in rules() today either way	n/a

Net: the only items that change generated output for realistic specs are query/additionalOperations (routes layer), defaultMapping (discriminator hydration), and itemSchema (streaming). Everything else is tolerate-and-ignore.

Parser dependency

devizzent/cebe-php-openapi does not support 3.2. README says 3.0.x/3.1.x, latest release 1.1.5 (2026-01-24), and there is an open issue: DEVizzent/cebe-php-openapi#41 "Support OpenAPI version 3.2" (opened 2026-03-20, no comments, no PR). Upstream cebe/php-openapi never even merged 3.1.

Concretely in the vendored code (src/spec/OpenApi.php): PATTERN_VERSION = '/^(3\.(0|1))\.\d+(-rc\d)?$/i', so getMajorVersion() returns unsupported for 3.2 and performValidation() would flag it. But we call cebe with validate: false, so neither fires. Unknown keys ($self, tag kind, query under a Path Item) are silently not mapped to typed attributes.

Options, roughly in order of preference:

1. Accept-and-degrade now (no dependency change): keep parsing 3.2 as we already do, add an explicit version gate plus warnings for dropped 3.2 constructs (see below).
2. PR the fork: extend PATTERN_VERSION, add query/additionalOperations to PathItem attributes, defaultMapping to Discriminator, itemSchema to MediaType, mediaTypes to Components. Issue 1.0.0: document what semver means for a code generator (versioning and regeneration policy) #41 is open and unclaimed, the maintainer seems receptive. Medium-sized but mechanical.
3. Read 3.2-only keys ourselves from the raw array (we already normalize schemas pre-cebe in SchemaNormalizer), bypassing typed access for the few keys we need. Works without waiting on upstream, costs us some parser-layer ugliness.

What we do today with a 3.2 document

Verified locally against a hand-written openapi: 3.2.0 spec with $self, tag kind, a query operation, and additionalOperations:

• Our own gate in SpecParser::assertOpenApiDocument only checks str_starts_with($version, '3.'), so 3.2.0 is silently accepted.
• Generation succeeds, exit 0: Data class, controller, routes all emitted.
• The query operation and the additionalOperations PURGE operation are silently dropped (routes.php contains only the GET, controller has one method). No warning anywhere. That silent loss is the main correctness risk.

Fixtures

Thin but real: OAI/learn.openapis.org ships official 3.2 examples under examples/v3.2/ (3.2-query-example.{yaml,json}, 3.2-tags-example.{yaml,json}). No large real-world 3.2 specs in our corpus sources yet; adoption is early. Plan: add the two official examples plus a hand-crafted petstore-3.2 exercising query, additionalOperations, defaultMapping, itemSchema.

Ecosystem and the badge

• openapi-generator: no 3.2 support, open issue when to support OpenAPI 3.2.0 ? OpenAPITools/openapi-generator#22728, blocked on swagger-parser ([Feature]: Support for OpenAPI Spec 3.2 swagger-api/swagger-parser#2248).
• openapi-typescript / oazapfts: no 3.2 claim found.
• Sibling openapi-zod-ts: README says "3.1.x primary target, 3.0.x best-effort", no 3.2 claim, no version hard-gate beyond that.
• openapi.tools oas-v32-early badge: criteria are informal, "among the earliest tools to adopt support for OpenAPI 3.2" (src/content/badges/oas-v32-early.md); current holders include redocly-cli, typespec, wiretap, clio. A PR against our tool entry claiming 3.2 support is the mechanism; we should only claim it once we at least parse 3.2 deliberately and handle or warn on the new operation keywords.

Recommended path

Two-stage:

1. 0.x quick win, accept-and-degrade honestly: explicitly recognize 3.2.x in SpecParser, emit build warnings when we encounter query, additionalOperations, in: querystring, itemSchema, or components.mediaTypes (read from the raw document, no cebe changes needed), and tolerate all metadata additions. This removes the silent-drop hazard at small cost and is defensible as "3.2: accepted, new operation types reported, not yet generated".
2. Full support: PR the DEVizzent fork (issue 1.0.0: document what semver means for a code generator (versioning and regeneration policy) #41) for the typed attributes, then generate Route::match(['QUERY'], ...) routes and controller methods for query/additionalOperations, wire defaultMapping into the morphable discriminator base, and decide whether itemSchema emits the item Data class. Claim the badge after stage 2, or after stage 1 if we are comfortable with "early adopter" meaning "parses and degrades loudly".

Effort guess: stage 1 is S, stage 2 is M overall (fork PR M, routes/controllers S/M, defaultMapping S, itemSchema M).

[benjamineckstein]

Split out: the small dependency-free stage 1 (explicit version gating, loud best-effort warnings for 3.2) is now #103 and is a pre-1.0 candidate. This issue stays as the post-1.0 full 3.2 support track (parser fork PR, QUERY routes, defaultMapping, itemSchema, fixtures, badge).

[benjamineckstein]

Update: the stage 2 path changed. Usage-surface and fork-vitality analysis (see #104) concluded we will not PR the DEVizzent fork; instead we replace the dependency with our own reader post-1.0, with 3.2 fixed fields typed from day one. This issue then becomes wiring the new typed surface into emission (QUERY routes, additionalOperations, defaultMapping, itemSchema). Depends on #104.