You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Operations are detected as changed when comparing for open api version 3.0.1 and 3.1.0 #858
The operations are detected as changed and only repeat the parameters e.g. query, sort request parameters in one case, path parameters in the others) while nothing has changed in the operations.
If we change the open api version in one definition to match the other, no changes are detected as expected
Report was generated by using the example code in home page by specifying rendering all changes i.e. HtmlRender htmlRender = new HtmlRender("Changelog", "http://deepoove.com/swagger-diff/stylesheets/demo.css", true);
Reproduced with the two attached specs — they differ only in the openapi field (3.0.1 vs 3.1.0) plus info.version (3.47.0 vs 3.48.0). On master (2.1.8-SNAPSHOT CLI, commit 63850d8):
- GET /sample-api/export
Parameter:
- Changed query in query
- Changed sort in query
- POST /sample-api/{id}/actions/CAN
Parameter:
- Changed id in path
- POST /sample-api/{id}/actions/DEL
Parameter:
- Changed id in path
API changes broke backward compatibility
So this is not just rendering noise — the compatibility verdict itself is wrong. Flipping openapi in the new spec back to 3.0.1 while keeping the info.version difference yields no_changes, which confirms info.version is ignored by the diff and the openapi field bump is the trigger.
Root cause: the two documents deserialize differently. A 3.0.1 parameter schema parses with type: "string", while in a 3.1.0 document swagger-parser stores the type keyword in the JSON Schema 2020-12 types list (types: ["string"]) and getType() comes back null. SchemaDiff.computeDiffForReal compares getType() raw, so every parameter schema looks like a type change string → null; a type change is treated as backward-incompatible, which is why the whole report turns red instead of just showing changes.
Fix options:
Compare the effective type set — the union of getType() and getTypes() — in SchemaDiff instead of raw getType(). Small, non-breaking, and it fixes both this false positive and the related false negative in Property type change on referenced component schema is silently ignored #910 (3.1 type changes on referenced component schemas being silently ignored). PR fix: detect property type changes on referenced component schemas in OpenAPI 3.1 #938 implements exactly this comparison; building its head and re-running the two specs from this issue gives No differences. Specifications are equivalent. If it lands, a regression fixture for this issue (a 3.0.1 vs 3.1.0 pair like the attached ones) would be a natural addition.
Normalizing at parse time (mirroring a single-element types back into type before diffing): touches every parsed schema and still wouldn't cover the composed-schema flattening path.
Special-casing the 3.0 → 3.1 openapi field bump as metadata-only: doesn't help, because the false change is produced per parameter schema, not at document level.
Activity
Inf1mum commentedon Nov 13, 2026
Reproduced with the two attached specs — they differ only in the
openapifield (3.0.1 vs 3.1.0) plusinfo.version(3.47.0 vs 3.48.0). On master (2.1.8-SNAPSHOT CLI, commit 63850d8):So this is not just rendering noise — the compatibility verdict itself is wrong. Flipping
openapiin the new spec back to3.0.1while keeping theinfo.versiondifference yieldsno_changes, which confirmsinfo.versionis ignored by the diff and theopenapifield bump is the trigger.Root cause: the two documents deserialize differently. A 3.0.1 parameter schema parses with
type: "string", while in a 3.1.0 document swagger-parser stores thetypekeyword in the JSON Schema 2020-12typeslist (types: ["string"]) andgetType()comes back null.SchemaDiff.computeDiffForRealcomparesgetType()raw, so every parameter schema looks like a type changestring → null; a type change is treated as backward-incompatible, which is why the whole report turns red instead of just showing changes.Fix options:
getType()andgetTypes()— inSchemaDiffinstead of rawgetType(). Small, non-breaking, and it fixes both this false positive and the related false negative in Propertytypechange on referenced component schema is silently ignored #910 (3.1 type changes on referenced component schemas being silently ignored). PR fix: detect property type changes on referenced component schemas in OpenAPI 3.1 #938 implements exactly this comparison; building its head and re-running the two specs from this issue givesNo differences. Specifications are equivalent. If it lands, a regression fixture for this issue (a 3.0.1 vs 3.1.0 pair like the attached ones) would be a natural addition.typesback intotypebefore diffing): touches every parsed schema and still wouldn't cover the composed-schema flattening path.openapifield bump as metadata-only: doesn't help, because the false change is produced per parameter schema, not at document level.