Fix #858: don't report identical schemas as changed when only the OpenAPI version differs

IN
2d ago
+454-0

Fixes #858

What

Comparing two specs that differ only in the openapi version field (3.0.1 vs 3.1.0, as attached in the issue) reported every operation as changed with bogus parameter type changes and flipped the verdict to INCOMPATIBLE.

Why

For OpenAPI 3.1 documents the parser (swagger-parser 2.1.31 / swagger-models 2.2.34) stores the type keyword in the JSON Schema 2020-12 types set and leaves Schema.getType() null, while OpenAPI 3.0 documents expose the same keyword only through Schema.getType(). The schema comparison uses the singular type, so each identical schema compared across the version boundary looked like a string -> null type change (a type change is backward-incompatible, which is why the whole report turned red).

How

Before diffing, when exactly one side of the comparison is an OpenAPI 3.1 document, a new document walker (SchemaTypeNormalizer) mirrors a single-element types set back into the singular type keyword — a lossless representation swap. Sets with zero or multiple types are left untouched, and same-version comparisons are unchanged, so this only removes the cross-version false positives.

This is deliberately kept out of SchemaDiff/SchemaDiffResult/ChangedSchema so it does not conflict with the other open 3.1-comparison PRs (#938, #962, #963).

Tests

New Issue858Test (regression pair taken from the issue's attached specs, tested in both directions plus the overall unchanged verdict):

  • fails on unpatched master (594183e) — 3/3 red, reproducing the issue,
  • passes with this change — no_changes in both directions.

Full mvn verify is green (core: 273 tests, cli: 13 tests).


Summary by cubic

Fixes #858 — comparing two specs that differ only in the openapi version field (3.0.1 vs 3.1.0) previously reported every operation as changed and flipped the verdict to INCOMPATIBLE.

The parser stores the type keyword in the JSON Schema 2020-12 types set for 3.1 documents and leaves Schema.getType() null, while 3.0 documents expose it only through getType(). When exactly one side is a 3.1 document, the new SchemaTypeNormalizer now mirrors single-element types sets back into the singular type before diffing. Sets with zero or multiple types are left untouched, and same-version comparisons are unchanged.

Adds a regression test using the specs from the issue, verified in both directions.