Repository navigation
Conversation
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>
There was a problem hiding this comment.
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)); |
There was a problem hiding this comment.
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()); |
There was a problem hiding this comment.
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #858
What
Comparing two specs that differ only in the
openapiversion 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 toINCOMPATIBLE.Why
For OpenAPI 3.1 documents the parser (swagger-parser 2.1.31 / swagger-models 2.2.34) stores the
typekeyword in the JSON Schema 2020-12typesset and leavesSchema.getType()null, while OpenAPI 3.0 documents expose the same keyword only throughSchema.getType(). The schema comparison uses the singular type, so each identical schema compared across the version boundary looked like astring -> nulltype 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-elementtypesset back into the singulartypekeyword — 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/ChangedSchemaso 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):594183e) — 3/3 red, reproducing the issue,no_changesin both directions.Full
mvn verifyis green (core: 273 tests, cli: 13 tests).Summary by cubic
Fixes #858 — comparing two specs that differ only in the
openapiversion field (3.0.1 vs 3.1.0) previously reported every operation as changed and flipped the verdict toINCOMPATIBLE.The parser stores the
typekeyword in the JSON Schema 2020-12typesset for 3.1 documents and leavesSchema.getType()null, while 3.0 documents expose it only throughgetType(). When exactly one side is a 3.1 document, the newSchemaTypeNormalizernow mirrors single-elementtypessets back into the singulartypebefore 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.