Definition of a breaking change

[dublintech]

Most API vendors follow something akin to Postel's law, but careful what you send and liberal in what you accept and as a result don't consider adding new attributes to a payload response a "breaking change".

However, something like changing the data type they would. But, OAS also supports format. So you can have a integer type and a format of int32 and int64. Wondering if you change the type is this considered a breaking change?

Can see any standard for this?

Would welcome thoughts.

[handrews]

I'm not aware of a standard that goes into that level of detail, but generally if something worked before and then doesn't work, that's a breaking change. So if a tool respects those format values, and you change from int64 to int32, that's breaking because larger integers used to work but now don't. If you go the other way around, that's fine - you support larger integers in addition to what you already supported.

This is a little more complex because tools are not required to recognize all format values, and are allowed to fall back to just using type, so it's possible to make a breaking change but not have the tools enforce it. format is always tricky, so check the tooling support. Those formats are in the OAS itself, so they're very likely to be supported.

Does that answer your question? Please let me know if I misinterpreted it!

[dublintech]

@handrews thanks. The closest I found was from the openapi diff tool. https://github.com/Tufin/oasdiff/blob/main/BREAKING-CHANGES-EXAMPLES.md

This is fairly extensive. It details lots of breaking changes, non breaking change and then "info - level" changes. Format changes are considered info-level.

[handrews]

That's a lot, certainly more than I have time to go through in detail. Some of those I feel are really an "it depends" - most of the time they probably are breaking changes, but there are weird corners. For example, if you add an allOf that only includes annotation keywords (like title), that's not really a breaking change the way it is if you add another constraint that invalidates previously-valid instances.

[LasneF]

notice that this tool does not handles OAS 3.1 but only OAS 3.0 even if the gap is not so big , looks it has been a challenge

[notEthan]

I am reminded of an old xkcd: every change is breaking

And, related, Hyrum's law

[handrews]

@dublintech It's not clear to me what the OAS can or should do here. Defining the meaning of "breaking change" for all APIs would be a dramatic extension of our scope into a different sort of standard. Currently, we describe APIs, but are as neutral as possible regarding how those APIs are designed. We intentionally want to be able to describe APIs that existed before someone tried to write an OpenAPI Description for them, and those APIs often grew in an ad-hoc manner.

I am inclined to declare this out-of-scope for this project, but would like @OAI/tsc to weigh in.

[LasneF]

I definitely agree, Breaking change definition is something that is opiniated , and depends on what you are doing
you might distinguish especially for OAS ,at least 3 models : "on the wire breaking change" , sdk generation breaking change , and may be functionnal breaking change ,

notice that one of the pilar of OAS is JSON schema where you have as well no formal breaking change definition I found only this one !
" A braking change occurs when JSON instance that was valid under the old schema becomes invalid under the new schema. "

it could be a starting point but a bit even this simple definition is challenging , for instance is removing a non mandatory query parameter is a breaking change , all depends is your client code rely on it or not , and on the context . is adding one is a breaking change ? it depends if the addition affect the run time execution

so i would say let the tooling to setup rules and definition for breaking change customizable , as similar to linter rules
you migh found some definition for instance there

here is one of the implementation tooling : https://github.com/pb33f/libopenapi/tree/66b73b3210510514efd47320a85d0dbb47204c89/what-changed
here is another may be more accurate definitinon

https://www.oasdiff.com/checks with the concept of breaking change level