> ## Content Index > Fetch the complete content index at: https://apisyouwonthate.com/llms.txt > Use this file to discover other available public pages before exploring further. # Breaking Change Detection in OpenAPI - URL: https://apisyouwonthate.com/blog/breaking-change-detection-in-openapi/ - Published: 2026-10-19T11:24:25.000Z - Updated: 2026-10-19T11:24:25.000Z - Description: A look at several approaches you can take to help stop breaking changes from sneaking up on you, using OpenAPI Tooling - Author: Phil Sturgeon - Tags: api-governance, openapi Nobody wants to see breaking changes sneak into an API, but how do you protect against them. [Contract testing](https://apisyouwonthate.com/blog/contract-testing-apis-laravel-php-openapi/) makes sure API code matches API descriptions like [OpenAPI](https://www.openapis.org/?ref=apisyouwonthate.com), but when the description changes at the same time as the code? API gateways start rejecting previously valid requests. Client applications break in weird and unobvious ways. The phone starts to rings. You have a bad day. OpenAPI does a great job of describing the entire contract of an API right now, but it doesn't get involved with chronological changes, so something else needs to handle seeing things change. For the majority of us we're already tracking OpenAPI in Git (or possibly Mercurial? Is that still a thing?) so pull requests kinda feel like something that could help, but staring into potentially thousands of lines of YAML to spot mistakes is not fun, efficient, or even particularly effective. Of course it's 2026 so immediately everyone must be thinking "I bet the answer is to crowbar some AI in there, that'll be reliant and affordable long term!" and yes there are people doing that. There are also good deterministic tools that work reliably which you could use instead. Breaking change detection tools basically compare a `before.yaml` and `after.yaml` document, or more conveniently they can use use CI/CD and Git in one of two ways. One is using the pull request mechanism, another is running against local commit histories. Here's how you might use `oasdiff`, the long-time champion of OpenAPI diffing, changelogs, and breaking change detection. This compares the local branch latest commit to remote branch `origin/main`. ``` $ oasdiff breaking origin/main:api/openapi.yaml HEAD:api/openapi.yaml ``` Just for the sake of a demo, I renamed a `GET` parameter from `/certificates` to `/certificates2`, replicating the sort of small problematic change caused by a cat walking over my keyboard. This is the output. ``` 1 changes: 1 error, 0 warning, 0 info error [api-path-removed-without-deprecation] at api/openapi.yaml in API GET /certificates/{certificate} api path removed without deprecation ``` There are two help nudges happening here. The first is that I don't have to skim through loads of YAML to find breaking changes that could have been made amidst a large change by somebody else. There could have been so many whitespace changes or 1000 fullstops added to descriptions so I didn't see it. Breaking change detectors skip all that, and give governance teams or design reviewers a chance to question whether that endpoint is meant to go away right now or not. The second benefit here is that it's pointing the API maintainer towards deprecation as a solution. Instead of just ripping the rug out from underneath all the clients, deprecation offers a chance for everyone to be warned that changes might be coming, and when paired with `Deprecation` and/or `Sunset` headers and automated deprecation warnings thrown by HTTP clients and SDK generators, this should help clients move away from the deprecated feature **before** it's removed. [API Evolution for REST/HTTP APIsThere are a lot of pros and cons to various approaches to API versioning, but that has been covered in depth before in API Versioning Has No “Right” Way. API evolution is making a comeback these days with GraphQL and gRPC advocates shouting about it. Whatever API paradigm or implementation![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/icon/apis-logo-square-a49b39d2-d6dd-442b-9fca-dc6f25484978.png)APIs You Won't HatePhil Sturgeon![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/thumbnail/evolution-31f43fc2-07e9-4f15-889d-761dffca1723.png)](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/) ## Automating breaking change detection Running a command locally is something that people might do now and then, but to make sure the APIs you manage are completely protected from being messed up by lazy humans or rogue LLMs, make sure to implement a break check on pull requests too. ```yaml name: oasdiff on: pull_request: branches: ["main"] permissions: contents: read pull-requests: write jobs: breaking-changes: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - run: git fetch --depth=1 origin ${{ github.base_ref }} - uses: oasdiff/oasdiff-action/breaking@v0 with: base: "origin/${{ github.base_ref }}:api/openapi.yaml" revision: "HEAD:api/openapi.yaml" fail-on: WARN allow-external-refs: true github-token: ${{ github.token }} ``` Change `api/openapi.yaml` to wherever the OpenAPI lives, and don't skimp on the `allow-external-refs: true` if you're using `$ref: schemas/foo.yaml` or it will ignore them and then say there weren't any problems. Oops! ## A plethora of tools for breaking changes I'll be honest this article was supposed to be an overview of some of the tools around, celebrating the launch of OpenAPI.Tools' new [Breaking Changes category](https://openapi.tools/categories/breaking-changes?ref=apisyouwonthate.com), but then I noticed `oasdiff` has a new website and some serious updates. For a long time oasdiff had a crunchy website and did not instill much confidence. I'd also struggled with countless errors following their hello world guides, but I think I was just seeing the new docs whilst installing the latest - but also outdated - code. I'm using [oasdiff](https://openapi.tools/tools/oasdiff?ref=apisyouwonthate.com) for [Protect Earth](https://protect.earth/?ref=apisyouwonthate.com)'s API now quite happily, but I've had a lot of success with [openapi-changes](https://openapi.tools/tools/openapi-changes?ref=apisyouwonthate.com) for clients too. [openapi-changes | OpenAPI.toolsThe world’s fastest, most beautiful, powerful and detailed OpenAPI change detection tool. Explore changes in OpenAPI descriptions. Go back into history and see what changed with each commit, or compare two different documents. Identifies all breaking changes, Powered by libopenapi.![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/icon/favicon-778b0adb-a97b-43f2-98b0-9f514216dd31.png)APIs You Won't HateAPIs You Won’t Hate![](https://openapi.tools/tools/openapi-changes.og.png)](https://openapi.tools/tools/openapi-changes?ref=apisyouwonthate.com) It's got some really snazzy CLI interfaces, but the GitHub Action was rudimentary and I had to handcraft a lot of GitHub integration by piping together some complicated bash scripts messing with Markdown snippets instead of getting that done out of the box. It did make some clients happily especially when oasdiff was not working, but it always seems to take a lot of faffing to get it running smoothly. It will also quite often complain about things that simply don't constitute actual breaking changes. [Redocly CLI](https://openapi.tools/tools/redocly-cli?ref=apisyouwonthate.com) also has breaking change detection, and I have to be honest I didn't know that until recently. The team went on a rampage adding every single OpenAPI utility you can think of to their CLI, and that must have gone in around then or shortly after snuck past me. Check it out and let me know in the comments. I've popped it into the [Breaking Changes category](https://openapi.tools/categories/breaking-changes?ref=apisyouwonthate.com) so folks can find it easily. ## Breaking changes are in the eye of the beholder It feels a bit late to ask ourselves this question, but: what are breaking changes in an API? Common answers will usually include a few of the following: - Renaming an endpoint. - Suddenly creating a new required property. - Deleting something from a response that a client was using. - Changing the type of a property from a string to an integer. - Increasing the allowed length of a string. These are some of the basics, but figuring out what is and is not a breaking change detection is an incredibly complex discussion. We could really get into some examples where non breaking changes are actually breaking, and breaking changes are not breaking at all... but some of this is probably best left to the philosophers or at least the API governance team, because it requires some very specific domain knowledge which these tools cannot have. The folks at `oasdiff` have laid out their full set of rules here: [OpenAPI Breaking Changes: The Complete List of Rules](https://www.oasdiff.com/docs/breaking-changes?ref=apisyouwonthate.com) and in general it's a solid list. Nothing that shouldn't be there, and lots of good rules that should. Other tools in the past have shouted at me for things like upgrading to OpenAPI v3.0 to v3.1, because I had the audacity to [follow the migration guide](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html?ref=apisyouwonthate.com) exactly (you'd hope so I wrote it!) and replace `type: string; nullable: true` with `type: ['string', 'null']` . Changes like that are *OpenAPI syntax* and are not related to the API contract itself. The API hasn't changed, and there cannot be a breaking change in the contract of the API if the API contract has not changed. ## Is the AI-based tooling any good? Since adding the [Breaking Changes category](https://openapi.tools/categories/breaking-changes?ref=apisyouwonthate.com) to [OpenAPI.Tools](https://openapi.tools/?ref=apisyouwonthate.com) a bunch of bots descended. with AI generated devtools that have AI generated websites and one PR was literally sent to us by `@grokbotdev`. Another came from `@Skyblueballykid` and I'm not sure which is worse. This all feels like [Throwaway Tooling](https://apisyouwonthate.com/newsletter/throwaway-tooling/), which will be abandoned as soon as they realise indie devtools have a long history of going bankrupt even when they solves a problem really well. I've successfully created and solve CMS's, invoice apps, and other downloadable or SaaS software, but that's done through stakeholder engagement and extensive domain knowledge, not guesswork and a chatbot. The other outcome for devtools lately has been to be just good enough to get scooped up by corporates, but these individual vibe coders have a smaller token budget than these same corporates, who can easily run the same sloppy command prompts as you without having to buy your "work". The OpenAPI ecosystem already has a problem with open-source tools vanishing and whole OpenAPI.Tools categories filling up with half-assed SaaS products, but now these SaaS products are just vibe coded surface level rubbish with vibe coded marketing sites and nobody behind the wheel when you report problems. Who knows how secure they'll be with your OAuth tokens and Git repository access. ## Conclusion I do not recommend you use AI generated tooling for breaking change detection, nor should you be trying to find tooling that consults the forgetful wizard to detect breaking changes in any APIs you actually care about. This is a deterministic problem with deterministic solutions, and for that reason you should stick to supporting open-source software. Use [oasdiff](https://openapi.tools/tools/oasdiff?ref=apisyouwonthate.com), [openapi-changes](https://openapi.tools/tools/openapi-changes?ref=apisyouwonthate.com), or [Redocly CLI](https://openapi.tools/tools/redocly-cli?ref=apisyouwonthate.com). All three of them support OpenAPI v3.1 and v3.2 so you can use them in any modern OpenAPI workflow.