Add OpenAPI 3.1 paired-fixture test harness (Phase 0)

IN
2d ago
+863-0

Fixes #948

What this provides

Phase 0: the test setup every later phase of the Stage 1 plan builds on. A fixture convention plus a harness that keeps the "same change, same verdict in every version" contract visible while the engine grows 3.1 support.

The harness (Oas31PairedFixturesTest) does three things:

  1. Pins the 3.0 baseline. A parameterized test asserts the documented 3.0->3.0 verdict per rule, so the stage goal "verdicts for 3.0 specs stay unchanged" is guarded from day one.
  2. Checks the Swagger 2.0 pair against the 3.0 verdict of the same rule (both go through the 3.0-shaped model today).
  3. Holds the not-yet-working parts of the contract as disabled tests, each naming the phase that fixes it, so the build stays green and each phase un-disables its own tests when it lands.

Fixture inventory

core/src/test/resources/oas31/<rule>/ with old-3.0.yaml, new-3.0.yaml, old-3.1.yaml, new-3.1.yaml - the same minimal document written in both syntaxes, one change per pair:

RuleChange3.0 vs 3.1 spelling3.0 verdict
type-changeproperty weight integer -> stringscalar type in bothincompatible
nullableproperty notes becomes nullablenullable: true vs type: [string, "null"]compatible
exclusive-boundsrequest minimum becomes exclusiveboolean exclusiveMinimum: true vs numeric exclusiveMinimum: 0incompatible
array-itemsitems of an array string -> integertype: array + items in bothincompatible
all-ofproperty type change inside an allOf memberallOf of refs in bothincompatible
one-ofproperty type change inside a oneOf memberoneOf of refs in bothincompatible
swagger2the type-change rule in Swagger 2.0definitions + swagger: "2.0"incompatible (2.0->2.0)

Known 3.1 gaps (disabled, with the phase that fixes each)

Same-version comparisons (3.1->3.1 must agree with 3.0->3.0) - all fixed by Phase 2, the engine reading 3.1 fields [#950]:

  • type-change: the engine compares getType(), which is null for 3.1 schemas; the type keyword lives in the types set (same root cause as [#938]/#910)
  • nullable: 3.1 nullability is "null" in the types set; the null rule is not implemented
  • exclusive-bounds: the 3.1 numeric exclusiveMinimum is not read (3.1 currently reports compatible where 3.0 reports incompatible)
  • array-items: items are compared only on ArraySchema; 3.1 arrays deserialize as JsonSchema
  • all-of: allOf is flattened only on ComposedSchema (same root cause as #938)
  • one-of: oneOf members are compared only on ComposedSchema

Cross-version comparisons and the written equivalence - fixed by Phase 3, converter wired in [#951]:

  • 3.0->3.1 for every rule reports a false incompatible (a 3.1 document has type == null, so the type gate fires on every comparison)
  • the same document written in 3.0 and in 3.1 reports changes instead of no changes (version noise, #858)

Fixture discipline follows the pattern used in #938: one rule per directory, minimal single-operation documents, and every comparison executable in isolation.


Summary by cubic

Adds the paired-fixture test harness that Phase 0 of the OpenAPI 3.1 support plan (#948) builds on. For six rules, the same minimal change is expressed as a 3.0 pair and a 3.1 pair under core/src/test/resources/oas31/<rule>/; the harness pins the documented 3.0→3.0 verdict, checks that a Swagger 2.0 pair for the type-change rule matches it, and keeps the comparisons that fail on today's engine as disabled tests so the build stays green.

Known gaps (disabled, with the phase that fixes each)

  • 3.1→3.1 verdict agreement is disabled until Phase 2 (#950), when the engine reads 3.1 schema fields (type in the types set, numeric exclusiveMinimum, items and composition on JsonSchema).
  • Mixed-version comparisons and the 3.0-vs-3.1 written equivalence are disabled until Phase 3 (#951), when the converter is wired in.