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
Draft
Oas 3.2 support (fix OAS 3.2 schema validation and align with 3.0/3.1)#3032AnastasiiaSvietlova wants to merge 3 commits into
AnastasiiaSvietlova wants to merge 3 commits into
Conversation
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
marked this pull request as draft
August 5, 2026 13:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2910.
Checklist
Does this PR introduce a breaking change?
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_2format detection (packages/formats/src/openapi.ts)schema,dialect,meta), wired into document validationoas3_1-only rules (oas3_1-servers-in-webhook,oas3_1-callbacks-in-webhook, theArrayPropertiesalias) to also coveroas3_2as3_2-no-deprecated-xml-attributeWhat this PR adds on top
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$dynamicAnchornested inside$defs.schema. AJV does not correctly resolve a$dynamicAnchordeclared 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 realtype/propertiesas unrecognized fields. In practice: any 3.2 document with a schema in a request/response body, parameter, or header failedoas3-schema— i.e. almost any real API.Fix: replaced the 5
$dynamicRef: "#meta"occurrences inv3.2/index.jsonwith a static$reftohttps://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 byv3.1/index.json. Verified both directions: previously-failing valid documents now pass, and invalid documents (badtypevalues) are still correctly rejected.Smaller fixes (see commit/diff for detail)
errorMessageannotationsv3.1/index.jsonhas, so OAS 3.2 gets equally readable errors instead of raw AJV dumps.terserbump reverted:package.jsonbumped it butyarn.lockwasn't updated, which would fail CI's immutable install. No connection to this PR's purpose, no security reason found.oasSchema.ts: the newoas3_2branch was a verbatim copy ofoas3_1's.oas3_2-no-deprecated-xml-attributeintentionally only flagsxml.attribute: true, notfalse(no actionable migration forfalse).oas3-schema.test.ts, plus newtest-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 newqueryHTTP method in operation-rules,$selfref resolution). Left out of scope here to keep this PR focused; worth tracking as separate follow-up issues.