Skip to content

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

Open
Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:fix/858-version-noise
Open

Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:fix/858-version-noise

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 16, 2026 •

Copy link
Copy Markdown

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.

Written for commit c296474. Summary will update on new commits.

View guided diff

What:
Comparing two specs that differ only in the openapi version field
(e.g. 3.0.1 vs 3.1.0) reported every operation as changed with bogus
parameter type changes, flipping the verdict to incompatible.

Why:
For OpenAPI 3.1 documents the parser 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
identical schemas compared across the version boundary looked like
type changes (string -> null).

How:
Before diffing, when exactly one side of the comparison is an OpenAPI
3.1 document, mirror a single-element types set back into the
singular type keyword via the new SchemaTypeNormalizer document
walker. A single-element set and the singular type denote the same
schema, so this is lossless; sets with zero or multiple types are
left untouched and same-version comparisons are unchanged. Adds the
specs from the issue as a regression fixture pair.

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

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java">

<violation number="1" location="core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java:124">
P2: Header Objects can carry their schema under `content`, but this walker only visits `header.getSchema()`. Cross-version comparisons can therefore still report identical content-backed response or component headers as type changes; walk `header.getContent()` at both header call sites.</violation>

<violation number="2" location="core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java:180">
P2: This normalization mutates caller-owned 3.1 schemas. Reusing one in a later 3.1-vs-3.1 comparison compares its populated `type` with a fresh parser's `null`, producing a false change; normalize deep copies instead.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

}
walkContent(apiResponse.getContent(), visited);
if (apiResponse.getHeaders() != null) {
apiResponse.getHeaders().values().forEach(header -> walkSchema(header.getSchema(), visited));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Header Objects can carry their schema under content, but this walker only visits header.getSchema(). Cross-version comparisons can therefore still report identical content-backed response or component headers as type changes; walk header.getContent() at both header call sites.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java, line 124:

<comment>Header Objects can carry their schema under `content`, but this walker only visits `header.getSchema()`. Cross-version comparisons can therefore still report identical content-backed response or component headers as type changes; walk `header.getContent()` at both header call sites.</comment>

<file context>
@@ -0,0 +1,183 @@
+    }
+    walkContent(apiResponse.getContent(), visited);
+    if (apiResponse.getHeaders() != null) {
+      apiResponse.getHeaders().values().forEach(header -> walkSchema(header.getSchema(), visited));
+    }
+  }
</file context>


private static void normalizeType(Schema<?> schema) {
if (schema.getType() == null && schema.getTypes() != null && schema.getTypes().size() == 1) {
schema.setType(schema.getTypes().iterator().next());

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This normalization mutates caller-owned 3.1 schemas. Reusing one in a later 3.1-vs-3.1 comparison compares its populated type with a fresh parser's null, producing a false change; normalize deep copies instead.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java, line 180:

<comment>This normalization mutates caller-owned 3.1 schemas. Reusing one in a later 3.1-vs-3.1 comparison compares its populated `type` with a fresh parser's `null`, producing a false change; normalize deep copies instead.</comment>

<file context>
@@ -0,0 +1,183 @@
+
+  private static void normalizeType(Schema<?> schema) {
+    if (schema.getType() == null && schema.getTypes() != null && schema.getTypes().size() == 1) {
+      schema.setType(schema.getTypes().iterator().next());
+    }
+  }
</file context>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Operations are detected as changed when comparing for open api version 3.0.1 and 3.1.0

1 participant