Skip to content

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

Open

Description

@hsav

By comparing the two definitions attached the only difference is the open api version (3.0.1 against 3.1.0)

sample-api_3.47.0_ALL.json
sample-api_3.48.0_ALL.json

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.

testDiff.html

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);

Activity

  1. added theissue type on Nov 27, 2025
  2. Inf1mum commented on Nov 13, 2026

    @Inf1mum

    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:

    1. 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.
    2. 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.
    3. 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.
  3. added this to the 3.0.0 milestone on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions