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.