Skip to content

Oas 3.2 support (fix OAS 3.2 schema validation and align with 3.0/3.1) - #3032

Draft
AnastasiiaSvietlova wants to merge 3 commits into
stoplightio:developfrom
AnastasiiaSvietlova:oas-3.2-support
Draft

Oas 3.2 support (fix OAS 3.2 schema validation and align with 3.0/3.1)#3032
AnastasiiaSvietlova wants to merge 3 commits into
stoplightio:developfrom
AnastasiiaSvietlova:oas-3.2-support

Conversation

@AnastasiiaSvietlova

Copy link
Copy Markdown

Fixes #2910.

Checklist

  • Tests added / updated
  • Docs added / updated

Does this PR introduce a breaking change?

  • Yes
  • No

Additional context

Builds on @mkistler's #2917, adding fixes found during review and finishing the test coverage. Co-authored with @mkistler to keep their original contribution intact and attributed.

This follow-up work (review, root-cause analysis, and fixes) was done with the help of AI (Claude Code), same as the original PR.

What #2917 added

  • oas3_2 format detection (packages/formats/src/openapi.ts)
  • The official OpenAPI 3.2 JSON Schema bundle (schema, dialect, meta), wired into document validation
  • Extended oas3_1-only rules (oas3_1-servers-in-webhook, oas3_1-callbacks-in-webhook, the ArrayProperties alias) to also cover oas3_2
  • A new rule, oas3_2-no-deprecated-xml-attribute

What this PR adds on top

⚠️ Main fix: oas3-schema rejected virtually every real OAS 3.2 document
This is the important one — please read this section.

The vendored 3.2 schema uses $dynamicRef: "#meta" (5 places, e.g. media-type.schema) to point at a $dynamicAnchor nested inside $defs.schema. AJV does not correctly resolve a $dynamicAnchor declared anywhere other than a schema resource's root — see ajv-validator/ajv#1745 and #1573 (a near-identical report against the OAS 3.1 schema, where other validators like Hyperjump/jschon handle the same schema correctly). Instead of resolving to the intended anchor, AJV fell back to re-validating the schema value against the document's own root rules, rejecting any real type/properties as unrecognized fields. In practice: any 3.2 document with a schema in a request/response body, parameter, or header failed oas3-schema — i.e. almost any real API.

Fix: replaced the 5 $dynamicRef: "#meta" occurrences in v3.2/index.json with a static $ref to https://spec.openapis.org/oas/3.2/dialect/2025-09-17 — the same workaround the AJV issue reporter used, and the same pattern already used successfully by v3.1/index.json. Verified both directions: previously-failing valid documents now pass, and invalid documents (bad type values) are still correctly rejected.

Smaller fixes (see commit/diff for detail)

  • Error-message parity: added the same custom errorMessage annotations v3.1/index.json has, so OAS 3.2 gets equally readable errors instead of raw AJV dumps.
  • Unrelated terser bump reverted: package.json bumped it but yarn.lock wasn't updated, which would fail CI's immutable install. No connection to this PR's purpose, no security reason found.
  • Deduped oasSchema.ts: the new oas3_2 branch was a verbatim copy of oas3_1's.
  • Documented a scope decision: oas3_2-no-deprecated-xml-attribute intentionally only flags xml.attribute: true, not false (no actionable migration for false).
  • Test coverage: OAS 3.2 cases added to oas3-schema.test.ts, plus new test-harness/scenarios/oas3.2/ CLI scenarios, mirroring existing 3.0/3.1 coverage.

The contributor's own AI-assisted coverage checklist identified some OpenAPI 3.2 features that aren't fully covered yet (e.g. xml.wrapped, the new query HTTP method in operation-rules, $self ref resolution). Left out of scope here to keep this PR focused; worth tracking as separate follow-up issues.

mkistler and others added 3 commits July 21, 2026 06:32
Works around an AJV $dynamicRef/$defs limitation (ajv#1745) that made
oas3-schema reject valid OAS 3.2 documents, adds missing error-message
parity, reverts an unrelated terser bump, and adds OAS 3.2 test coverage.

Co-authored-by: Mike Kistler <mkistler@sbcglobal.net>
@AnastasiiaSvietlova
AnastasiiaSvietlova requested a review from a team as a code owner August 5, 2026 12:43
@AnastasiiaSvietlova
AnastasiiaSvietlova marked this pull request as draft August 5, 2026 13:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for OpenAPI 3.2

2 participants