OpenAPI breaking changes are the API bugs that pass every test you own: the server works, the new spec is valid, and a mobile app that was released last month starts failing because a field it reads is gone. The fix is to compare the spec in each pull request with the spec on the base branch and fail the build when a change would break existing clients. This guide does that with oasdiff, an open-source command-line tool: locally against git refs, in GitHub Actions with annotations on the diff, with a committed policy file, an ignore list for changes you accept on purpose, deprecation dates and an automatic check for a major version bump.

From my own work: On API projects I review, breaking changes rarely come from big redesigns, which everybody discusses. They come from small cleanups: renaming
userIdtouser_id, tightening an enum, or making a query parameter required because the new code needs it. A contract check in CI turned those from production incidents into a red check that starts a conversation in the pull request.
What counts as an OpenAPI breaking change
A change is breaking when a client written against the old contract stops working against the new one. That depends on the direction of data. For requests, the server becoming stricter breaks clients. For responses, the server sending less, or something different, breaks clients.
| Change | Why it matters | Usually |
|---|---|---|
| Remove an operation or path | Existing calls fail with 404 or 405 | Breaking |
| Add a required parameter or request property | Old requests miss it and are rejected | Breaking |
| Make an optional request field required | Same as above | Breaking |
| Remove a request enum value | Clients sending it are rejected | Breaking |
| Remove or rename a response property | Client code reading it gets undefined | Breaking |
| Change a property type | Parsing and validation fail | Breaking |
| Add a response enum value | Strict clients may not handle it | Warning |
| Add an optional request field or a response property | Old clients ignore it | Safe |
| Add a new operation | Nobody calls it yet | Safe |
oasdiff gives every change a level: ERR for a definite breaking change, WARN for one that cannot be confirmed from the spec alone, and INFO for a non-breaking change (oasdiff). The breaking command reports errors and warnings; changelog reports all three. The spec format itself is defined in the OpenAPI Specification.
Install oasdiff and run it locally
# macOS
brew install oasdiff
# any OS with Go installed
go install github.com/oasdiff/oasdiff@latest
# or without installing anything
docker run --rm -t -v "$PWD:/specs" -w /specs tufin/oasdiff breaking old.yaml new.yaml
oasdiff --version
oasdiff reads specs from files, URLs or git revisions in ref:path form, so you can compare the working copy with the main branch without checking anything out:
git fetch origin main
# breaking changes only
oasdiff breaking origin/main:openapi.yaml openapi.yaml
# everything that can affect consumers, breaking or not
oasdiff changelog origin/main:openapi.yaml openapi.yaml
# exit code 1 when there is at least one ERR (use WARN to include warnings)
oasdiff breaking origin/main:openapi.yaml openapi.yaml --fail-on ERR
echo "exit: $?"
# compare two released versions
oasdiff changelog v1.4.0:api/openapi.yaml v1.5.0:api/openapi.yaml
A typical result for a renamed response field looks like this, one block per change with the level, the operation and a message, which is the text you will later copy into an ignore file if the change is intended:
1 changes: 1 error, 0 warning, 0 info
error [response-property-removed] at openapi.yaml
in API GET /users/{id}
removed the required property 'userId' from the response with the '200' status
Treat that output format as illustrative; the exact wording comes from oasdiff’s check list, which you can print with oasdiff checks changelog.
A committed policy: .oasdiff.yaml
oasdiff looks for .oasdiff.yaml in the directory where it runs, and the configuration file accepts the same options as the command line (oasdiff config files). Keeping policy in the repository means developers get the same answer locally as CI does.
# .oasdiff.yaml
fail-on: ERR
exclude-elements: # ignore documentation-only edits
- description
- title
- summary
err-ignore: ./oasdiff-err-ignore.txt
severity-levels: ./oasdiff-levels.txt
# oasdiff-levels.txt (check-id level: err, warn, info or none)
response-non-success-status-removed err
api-tag-removed none
Raising a check to err makes it block merges under fail-on: ERR; setting it to none silences it. Start with the defaults and adjust only after you have seen a few weeks of real pull requests.
Run the OpenAPI breaking changes check in GitHub Actions
This workflow uses the CLI directly, so nothing leaves the runner. It fetches full history so the base branch ref exists, fails on errors, writes annotations onto the changed lines, and always puts a readable changelog in the job summary:
# .github/workflows/api-contract.yml
name: api-contract
on:
pull_request:
paths:
- 'openapi.yaml'
- '.oasdiff.yaml'
- 'oasdiff-*.txt'
permissions:
contents: read
jobs:
breaking-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0 # makes origin/<base branch> available
- uses: actions/setup-go@v7
with:
go-version: stable
- name: Install oasdiff
run: go install github.com/oasdiff/oasdiff@v1.39.0
- name: Changelog in the job summary
run: |
{
echo '## API changes'
oasdiff changelog "origin/${{ github.base_ref }}:openapi.yaml" openapi.yaml --format markdown
} >> "$GITHUB_STEP_SUMMARY"
- name: Fail on breaking changes
run: |
oasdiff breaking "origin/${{ github.base_ref }}:openapi.yaml" openapi.yaml
--format githubactions --fail-on ERR
The githubactions format prints workflow commands that GitHub turns into annotations on the Files changed tab (GitHub Docs: workflow commands). Pin the oasdiff version and update it on purpose, like any other dependency, so a new check does not fail unrelated pull requests overnight.
If you prefer a ready-made step, the official action does the same comparison and can post a pull request comment (oasdiff-action). By default it also uploads an encrypted copy of both specs to create a side-by-side review link. For a private API, set review: false so no spec leaves CI:
permissions:
contents: read
pull-requests: write # for the PR comment
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 }}:openapi.yaml'
revision: 'HEAD:openapi.yaml'
fail-on: ERR
review: false
Make the job a required status check in the branch protection rules, or the red check is only advice. If your repository has both checks for code and contract, the same pattern as the GitHub Actions CI guide for WordPress plugins applies: one workflow per concern, each a required check.
When the spec is generated from code
Frameworks such as FastAPI, NestJS and Spring can generate the spec from code. Commit the generated file anyway, and add a CI step that regenerates it and fails if it differs. That keeps the reviewed spec and the running code in sync, and gives oasdiff a stable file to compare:
# FastAPI example: regenerate and check that the committed spec is current
- run: |
python -c "import json; from app.main import app; print(json.dumps(app.openapi(), indent=2, sort_keys=True))" > openapi.json
git diff --exit-code openapi.json || {
echo "::error::openapi.json is out of date. Regenerate it and commit the result."
exit 1
}
oasdiff reads JSON as well as YAML, so point the comparison at openapi.json. For APIs split into one spec per service, oasdiff has a composed mode that compares globs of files instead of a single document.
Accepting a breaking change on purpose
Sometimes a breaking change is correct: the spec described behaviour the server never had, or every client has already moved. Do not disable the check. Add the change to the ignore file named in err-ignore, with a date and a reason. Each line needs the method and path and the change description; extra text is allowed, so the file doubles as a record of decisions:
# oasdiff-err-ignore.txt
- 2026-11-18 GET /users/{id} removed the required property 'userId' from the response with the '200' status
Reason: replaced by user_id in v2; the v1 mobile app is no longer supported (ticket API-412).
Get the exact description with oasdiff breaking ... --format singleline, which prints one change per line and is designed for preparing ignore files. Review the ignore file like code; it is your public list of broken promises.
Deprecate first, remove later
The kinder path is to deprecate before removing. Mark the operation or parameter with deprecated: true and announce a removal date with the x-sunset extension in RFC 3339 date format. oasdiff then allows the removal on or after that date and reports it as breaking if you remove it earlier, or move the date earlier:
paths:
/v1/users/{id}:
get:
deprecated: true
x-sunset: "2027-03-31"
summary: Get a user (use /v2/users/{id})
Pair the spec change with a Deprecation or Sunset response header and a note in your changelog, so clients that never read the spec still find out. Designing operations that tolerate retries and partial updates, as in the idempotent API design guide and the JSON Patch vs Merge Patch guide, also reduces how often you need to break anything.
Enforce a major version bump
If info.version follows Semantic Versioning, a breaking change should come with a new major version (Semantic Versioning). oasdiff can enforce that instead of failing on every breaking change: with --fail-on MISSING-VERSION-BUMP it fails only when it finds a breaking change and info.version did not get a major increase.
oasdiff breaking origin/main:openapi.yaml openapi.yaml --fail-on MISSING-VERSION-BUMP
This suits public APIs that publish versioned releases. For internal APIs with a single deployed version, plain --fail-on ERR plus the ignore file is usually simpler, because a version number does not help a client that is already deployed.
OpenAPI breaking changes checklist
- The spec is committed, and regenerated and verified in CI if it comes from code.
- oasdiff pinned to a version, run against
origin/<base>:openapi.yaml. --fail-on ERRas a required status check, with annotations and a changelog summary.- Policy in
.oasdiff.yaml, accepted changes in a dated ignore file. - Removals preceded by
deprecated: trueandx-sunset. - Major version bump enforced for public, versioned APIs.
Breaking a client is one kind of outage; overloading it is another. The API rate limiting guide covers the server side of protecting a public API.
Want this done on your own server or site?
I am Saizul Amin, a web developer and technical SEO consultant. I set up and harden VPS servers, migrate WordPress sites, fix indexing problems and build automations. See my portfolio or get in touch.
FAQ
What is a breaking change in OpenAPI?
A change that makes a client written against the old spec fail against the new one, such as removing an endpoint, adding a required request field, removing a response property or changing a type. Adding optional fields and new endpoints is usually safe.
How do I detect OpenAPI breaking changes automatically?
Run oasdiff breaking in CI with the base branch spec and the pull request spec, for example origin/main:openapi.yaml and openapi.yaml, and add –fail-on ERR so the job fails when a definite breaking change is found.
What is the difference between oasdiff breaking and changelog?
breaking reports only errors and warnings, the changes that can break clients. changelog reports every change that can affect consumers, including non-breaking info level changes, which makes it useful for release notes.
How do I allow an intentional breaking change?
Add the change description to the file referenced by err-ignore, with the method, path, a date and the reason. The check keeps running for every other change.
Does the oasdiff GitHub Action upload my spec?
By default the breaking action uploads an encrypted comparison to create a side-by-side review link. Set review to false, or run the CLI directly as shown in this guide, if no spec should leave CI.
Sources
- oasdiff on GitHub
- oasdiff GitHub Action
- OpenAPI Specification (latest)
- Semantic Versioning 2.0.0
- GitHub Docs: Workflow commands

Saizul Amin is an AI agent developer, AI automation engineer and full-stack software developer from Dhaka, Bangladesh. He builds any kind of AI agent, AI automation and custom software for any business. Portfolio: https://saizul.com

