test: prove OpenAPI 3.0 and 3.1 support, and fix the extension loss it found - #15
Open
AdamFiser wants to merge 20 commits into
Open
test: prove OpenAPI 3.0 and 3.1 support, and fix the extension loss it found#15AdamFiser wants to merge 20 commits into
AdamFiser wants to merge 20 commits into
Conversation
Header, SecurityScheme and OAuthFlow silently dropped x- specification extensions on round-trip, unlike every other schema class. Wire in VendorExtensions the same way Contact and Server already do.
Add an x- key to a Header, a Security Scheme and an OAuth Flow Object in both complete documents so VersionSupportTest's round-trip assertion proves the extension fix end to end, not just the isolated unit tests.
AdamFiser
marked this pull request as ready for review
August 3, 2026 07:19
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.
The test suite round-trips eleven real-world documents, seven declaring 3.0 and four declaring
3.1. Being real-world documents, they only use the fields their authors needed, so three 3.1
additions are exercised by nothing at all:
webhookswebhook-example.yamljsonSchemaDialecttype: mutualTLScomponents.pathItemsThe library implements all of them - but nothing in the repository proved it, and
.docs/README.mdstill described the package as a 3.0 implementation.
This adds one complete document per supported version, each using every field its version
defines, and a test making three assertions about it:
fromArray()followed bytoArray()returns the document unchanged.VersionValidatorreports no problem against the version the document declares.document. This works by relabelling the document to the oldest supported version and requiring
the validator to complain about each one, so the test needs no copy of the validator's path
resolution.
The third assertion is why
FIELD_INTRODUCED_INandVALUE_INTRODUCED_INbecamepublic const-the only visibility change in
src/. They are declarative data describing what the library knowsabout versions, which is what a coverage assertion needs to read. Reflection would couple the test
invisibly; restating the list in the test would let it drift.
The complete documents immediately found a bug. Specification extensions were being dropped on
three objects that OpenAPI allows them on:
Header,SecuritySchemeandOAuthFlowhad noVendorExtensionssupport at all - the samedefect that was already fixed for
Contact, surviving in three more classes. It is fixed here, eachwith a test that reproduces the loss first, and both fixtures now carry
x-keys on those objectsso the round trip guards them from now on. Every other extensible object was checked and is clean.
The practical effect of assertion 3: when 3.2 support lands, it fails until
complete-3-2.yamlexercises the new fields. Completeness of future documents is enforced by the test, not by reviewer
memory.
3.2 is deliberately absent from the version table.
Parameter::IN_QUERYSTRINGandPathItem::OPERATION_QUERYare proposed separately in #14, but without a complete 3.2 document theclaim would be unproven - the very problem this pull request fixes.
The documentation states only what the test enforces, including the one caveat that "every field"
cannot be taken literally: the specification makes some fields mutually exclusive, so no single
document can carry both
license.identifierandlicense.url.Would you consider tagging a release once this is in master? With 3.0 and 3.1 support now backed
by tests, plus #10-#13 already merged, there is a meaningful amount of unreleased work on
master.