Add OpenAPI 3.1 paired-fixture test harness (Phase 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:
- 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.
- Checks the Swagger 2.0 pair against the 3.0 verdict of the same rule (both go through the 3.0-shaped model today).
- 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:
| Rule | Change | 3.0 vs 3.1 spelling | 3.0 verdict |
|---|---|---|---|
type-change | property weight integer -> string | scalar type in both | incompatible |
nullable | property notes becomes nullable | nullable: true vs type: [string, "null"] | compatible |
exclusive-bounds | request minimum becomes exclusive | boolean exclusiveMinimum: true vs numeric exclusiveMinimum: 0 | incompatible |
array-items | items of an array string -> integer | type: array + items in both | incompatible |
all-of | property type change inside an allOf member | allOf of refs in both | incompatible |
one-of | property type change inside a oneOf member | oneOf of refs in both | incompatible |
swagger2 | the type-change rule in Swagger 2.0 | definitions + 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 comparesgetType(), 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 implementedexclusive-bounds: the 3.1 numericexclusiveMinimumis not read (3.1 currently reports compatible where 3.0 reports incompatible)array-items: items are compared only onArraySchema; 3.1 arrays deserialize asJsonSchemaall-of:allOfis flattened only onComposedSchema(same root cause as #938)one-of: oneOf members are compared only onComposedSchema
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 (
typein the types set, numericexclusiveMinimum,itemsand composition onJsonSchema). - Mixed-version comparisons and the 3.0-vs-3.1 written equivalence are disabled until Phase 3 (#951), when the converter is wired in.