Skip to content

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
contributte:masterfrom
AdamFiser:test/version-support-documents
Open

test: prove OpenAPI 3.0 and 3.1 support, and fix the extension loss it found#15
AdamFiser wants to merge 20 commits into
contributte:masterfrom
AdamFiser:test/version-support-documents

Conversation

@AdamFiser

@AdamFiser AdamFiser commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

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:

3.1 addition Covered before this pull request?
webhooks yes, webhook-example.yaml
jsonSchemaDialect no
type: mutualTLS no
components.pathItems no

The library implements all of them - but nothing in the repository proved it, and .docs/README.md
still 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:

  1. fromArray() followed by toArray() returns the document unchanged.
  2. VersionValidator reports no problem against the version the document declares.
  3. Every field the validator records as introduced in that version actually appears in the
    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_IN and VALUE_INTRODUCED_IN became public const -
the only visibility change in src/. They are declarative data describing what the library knows
about 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:

MISSING ...responses.200.headers.X-Rate-Limit.x-internal
MISSING components.securitySchemes.api_key.x-internal
MISSING components.securitySchemes.petstore_auth.flows.implicit.x-internal

Header, SecurityScheme and OAuthFlow had no VendorExtensions support at all - the same
defect that was already fixed for Contact, surviving in three more classes. It is fixed here, each
with a test that reproduces the loss first, and both fixtures now carry x- keys on those objects
so 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.yaml
exercises 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_QUERYSTRING and
PathItem::OPERATION_QUERY are proposed separately in #14, but without a complete 3.2 document the
claim 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.identifier and license.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.

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 AdamFiser changed the title test: prove OpenAPI 3.0 and 3.1 support with complete documents test: prove OpenAPI 3.0 and 3.1 support, and fix the extension loss it found Aug 3, 2026
@AdamFiser
AdamFiser marked this pull request as ready for review August 3, 2026 07:19
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.

1 participant