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

[reuvenharrison]

Hi all, dropping in as the author of oasdiff (thanks @dublintech for the mention).

A bit of perspective from 5 years of trying to answer "is this breaking?" for real-world API descriptions:

Rough consensus and running code. In oasdiff I've consistently prioritized functionality and usability over formality. The catalog (currently ~470 check IDs, browsable with the oasdiff checks command) grew empirically: every check is something a user or contributor hit in a real spec and reported, and the rule was added once the behavior was clear enough to act on. There was never a moment where I sat down and derived the catalog from first principles, partly because no such first principles exist anywhere in the ecosystem. I have made one attempt at a more rigorous tree-shaped model on the side (location × action × object, with severity layered as policy) which currently drives a subset of the catalog, but it has always been a side track to the running-code work, not a prerequisite.

Open source as a completeness lever. Going open and transparent has been the single biggest factor in catalog growth: people show up with edge cases I would never have found on my own. The format-direction asymmetry in this thread (int64 → int32 narrowing vs int32 → int64 widening) is exactly the kind of subtle, directional rule that only surfaces from contact with real specs. Even 5 years in, I'm still uncovering gaps. One motivated by this very discussion: adding an allOf subschema whose body is only annotation keywords (title, description, examples, default, externalDocs, $comment) was flagging as breaking under --fail-on WARN, even though it doesn't reject any previously-valid payload. Just shipped in v1.18.0 as eight new INFO-level check IDs. The deeper signal: the surface area is genuinely bigger than any one tool's empirical coverage.

One pointer for the OP: OAS 3.1 is fully supported in oasdiff today, including an oasdiff upgrade subcommand for the 3.0 → 3.1 conversion. Useful if you want to start describing your APIs more precisely, since the JSON Schema alignment in 3.1 makes type/format rules much easier to reason about (directly relevant to your int32/int64 question).

If anyone in this thread is interested in working together on the formal model, whether under the OAI umbrella or alongside it, I would welcome the collaboration; happy to seed it with the tree as a starting point.

And, while I'm here: thanks to the oasdiff community of users, contributors, and reviewers who have reported missing cases, opened PRs, and pushed back on misclassifications over the years.

Reuven