Should same 'shapes' be considered non breaking even if they have a different 'name'?

[ojii]

One of my types in my API spec changed from {'enum': ['a', 'b'], 'type': 'string'} to {'$ref': '#/definitions/Foo'} with that definition being {'enum': ['a', 'b'], 'type': 'string'}.

I would argue that this is not a breaking change and oasdiff should allow it. Is there a reason this should be considered breaking?

[reuvenharrison]

Indeed, this is not a breaking change.
Could you please provide a full example to to replicate the problem?

[ojii]

Ref:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Example",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Index",
        "operationId": "get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Data"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Data": {
        "properties": {
          "value": {
            "$ref": "#/components/schemas/Values"
          }
        },
        "type": "object",
        "required": [
          "value"
        ],
        "title": "Data"
      },
      "Values": {
        "type": "string",
        "enum": [
          "a",
          "b"
        ],
        "title": "Values",
        "description": "An enumeration."
      }
    }
  }
}

inlined:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Example",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Index",
        "operationId": "get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Data"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Data": {
        "properties": {
          "value": {
            "type": "string",
            "enum": [
              "a",
              "b"
            ],
            "title": "Values",
            "description": "An enumeration."
          }
        },
        "type": "object",
        "required": [
          "value"
        ],
        "title": "Data"
      }
    }
  }
}

[reuvenharrison]

Running oasdiff breaking spec_ref.json spec_inline.json with the specs above returns an empty result (no breaking changes).
Am I missing something?

[ojii]

Thank you so much for all your help. Before I throw the monster that is our api spec at you, I think I figured it out and the problem seems to be that for reasons I do not understand (yet), my tooling inserts a 'useless' allOf with just a single member.

base:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Example",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Index",
        "operationId": "get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Data"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Data": {
        "properties": {
          "value": {
            "type": "string",
            "enum": [
              "a",
              "b"
            ],
            "title": "Values",
            "description": "An enumeration."
          }
        },
        "type": "object",
        "required": [
          "value"
        ],
        "title": "Data"
      }
    }
  }
}

revision:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Example",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Index",
        "operationId": "get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Data"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Data": {
        "properties": {
          "value": {
            "allOf": [
              {
                "type": "string",
                "enum": [
                  "a",
                  "b"
                ],
                "title": "Values",
                "description": "An enumeration."
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "value"
        ],
        "title": "Data"
      }
    }
  }
}

breaking:

paths:
    modified:
        /:
            operations:
                modified:
                    GET:
                        responses:
                            modified:
                                "200":
                                    content:
                                        mediaTypeModified:
                                            application/json:
                                                schema:
                                                    properties:
                                                        modified:
                                                            value:
                                                                allOf:
                                                                    added:
                                                                        - RevisionSchema[0]
                                                                type:
                                                                    from: string
                                                                    to: ""
                                                                title:
                                                                    from: Values
                                                                    to: ""
                                                                description:
                                                                    from: An enumeration.
                                                                    to: ""
                                                                enum:
                                                                    enumDeleted: true
                                                                    deleted:
                                                                        - a
                                                                        - b
endpoints:
    modified:
        ?   method: GET
            path: /
        :   responses:
                modified:
                    "200":
                        content:
                            mediaTypeModified:
                                application/json:
                                    schema:
                                        properties:
                                            modified:
                                                value:
                                                    allOf:
                                                        added:
                                                            - RevisionSchema[0]
                                                    type:
                                                        from: string
                                                        to: ""
                                                    title:
                                                        from: Values
                                                        to: ""
                                                    description:
                                                        from: An enumeration.
                                                        to: ""
                                                    enum:
                                                        enumDeleted: true
                                                        deleted:
                                                            - a
                                                            - b
components:
    schemas:
        modified:
            Data:
                properties:
                    modified:
                        value:
                            allOf:
                                added:
                                    - RevisionSchema[0]
                            type:
                                from: string
                                to: ""
                            title:
                                from: Values
                                to: ""
                            description:
                                from: An enumeration.
                                to: ""
                            enum:
                                enumDeleted: true
                                deleted:
                                    - a
                                    - b

[reuvenharrison]

Glad that you found it :-)

Some comments:

1. the output you sent above is the diff, not the breaking changes
2. to get the breaking changes use the breaking subcommand: oasdiff breaking file1 file2
3. oasdiff has a --flatten flag to deal with situations like this: oasdiff breaking file1 file2 --flatten
4. there is a bug in the flatten logic which causes a diff for title and description, @tcdsv is fixing it

[ojii]

with breaking instead of diff and --flatten it indeed no longer complains! thank you so much!

[ojii]

is there any chance to get --flatten for diff? our definition of breaking is probably quite a lot stricter than what the breaking subcommand does

[reuvenharrison]

Yes, diff already supports the flatten flag