Read the OpenAPI 3.1 type keyword in the type and null rules

IN
2d ago
+591-2

Part of #950 — Phase 2, area 1 of 4: types and null. Prior art: #938 (same root cause for referenced component schemas); the fixture pairs reuse the Phase 0 harness layout from #961.

Spec

The engine picked its type comparison by the Java class shape. The type gate in SchemaDiff#computeDiffForReal compared getType(), which is null for OpenAPI 3.1 schemas (the type keyword lands in the types set at deserialization), so a 3.1→3.1 type change compared null with null and was silently dropped. Nullability had the same gap: in 3.1 type: [string, "null"] is the nullable spelling, but nothing in the engine read "null" from the types set, so adding it produced no_changes.

Implementation

  • New SchemaTypes helper in utils (the issue's small helper, one place for the keyword): reads the type keyword from both shapes while the phase is in progress — getType() for 3.0/Swagger 2.0, getTypes() for 3.1 — and splits it into the two things the rules reason about: the set of non-null types, and whether "null" is one of them.
  • The type gate now compares SchemaTypes.types(left)/types(right) instead of the raw getType() strings. A difference in the non-null type set still takes the exact same getTypeChangedSchema path, so classification stays identical to 3.0 (INCOMPATIBLE via changedType).
  • "null" only goes through the existing null rule: SchemaDiffResult feeds ChangedNullable with SchemaTypes.nullableValue(...) — the 3.0 nullable flag when it is set, otherwise the 3.1 "null" type. Raw nullable values are preserved for 3.0 documents, so ChangedNullable#getLeft()/getRight() keep their old values there (pinned by the existing SchemaDiffTest#changeNullableHandling).

Only existing verdict rules are used; boolean-sibling handling (3.1 exclusiveMinimum: <value> form) is not touched — that is the numeric-bounds area.

Fixtures and tests

Paired fixtures under core/src/test/resources/oas31/<rule>/ (old/new × 3.0/3.1, same layout as #961):

  • type-change and nullable — the harness's own files, byte-identical, so the two branches merge cleanly; this PR is what un-disables their same-version comparisons there.
  • type-multi — reordering type: [integer, string] → [string, integer] is not a change (set comparison; no 3.0 spelling exists for a multi-type keyword, so the 3.0 pair encodes the no-change baseline).
  • null-removal — dropping "null" from the types follows the same COMPATIBLE verdict as the 3.0 nullable rule.

Oas31TypesNullTest (parameterized): 3.0→3.0 keeps the documented verdict, 3.1→3.1 agrees with it, and the same spec written in 3.0 and in 3.1 diffs to no changes (for the rules whose spellings encode the same document). SchemaTypesTest pins the helper contract on constructed schemas. Cross-version comparisons (3.0 old against 3.1 new) stay with Phase 3 (#951).

Verification

Full suite green: core 289 tests (270 on master, +19 new; same 2 pre-existing skips), maven plugin 13. No existing test changed; 3.0 verdicts are unchanged.

Deliberately out of scope

  • Composed schema flattening and the addSchema merge (getTypes()/nullability propagation) — area 4 (also needed by #938's full fix).
  • items on non-ArraySchema — area 3. Numeric bounds — area 2.
  • DefaultPathMatcher's type equality and the renderers' getType() display reads — not verdict rules; left for the phase-end sweep.
  • Phase 3 (#951): 3.0→3.1 conversion and version noise (#858).

Signed-off-by: Inf1mum vadimlazuk5@gmail.com


Summary by cubic

Fixes 3.1→3.1 schema comparisons silently missing type changes and nullability changes. The engine compared getType(), which is null for OpenAPI 3.1 schemas (the type keyword is in the types set), so type diffs compared null with null and adding "null" produced no_changes.

Changes

  • New SchemaTypes helper reads the type keyword from both 3.0/Swagger 2.0 (getType()) and 3.1 (getTypes()) shapes.
  • The type gate compares the set of non-null types; type changes still classify as INCOMPATIBLE as in 3.0.
  • "null" routes through the existing null rule and feeds ChangedNullable; 3.0 nullable flag values are preserved.
  • Reordering a multi-type keyword ([integer, string] → [string, integer]) is not a change; cross-version comparisons stay with Phase 3.

Tests

  • Paired 3.0/3.1 fixtures for type-change, nullable, type-multi, and null-removal.
  • 3.1→3.1 verdicts match the documented 3.0 verdicts; the same spec written in both versions diffs to no changes.
  • Full suite green (289 core tests, +19 new); no existing test or 3.0 verdict changed.