Read the OpenAPI 3.1 type keyword in the type and null rules
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
SchemaTypeshelper inutils(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 rawgetType()strings. A difference in the non-null type set still takes the exact samegetTypeChangedSchemapath, so classification stays identical to 3.0 (INCOMPATIBLEviachangedType). "null"only goes through the existing null rule:SchemaDiffResultfeedsChangedNullablewithSchemaTypes.nullableValue(...)— the 3.0nullableflag when it is set, otherwise the 3.1"null"type. Raw nullable values are preserved for 3.0 documents, soChangedNullable#getLeft()/getRight()keep their old values there (pinned by the existingSchemaDiffTest#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-changeandnullable— 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— reorderingtype: [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 sameCOMPATIBLEverdict as the 3.0nullablerule.
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
addSchemamerge (getTypes()/nullability propagation) — area 4 (also needed by #938's full fix). itemson 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
SchemaTypeshelper 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
INCOMPATIBLEas in 3.0. "null"routes through the existing null rule and feedsChangedNullable; 3.0nullableflag 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.