What's new in oasdiff

With the nullability checks in oasdiff v1.23.0, the rule catalog reached a round number: 500 kinds of API changes detected, each classified by the OpenAPI object it affects, the kind of change, and whether it breaks existing clients.

The complete list is generated from the CLI itself on every release, so what you see there is exactly what runs in your CI.

OpenAPI has three equivalent ways to make a schema nullable: nullable: true (3.0), type: [string, "null"] (3.1), and wrapping in oneOf: [{type: "null"}, ...], the common idiom for $ref'd schemas. oasdiff now treats all three as one thing and reports a single, correctly-leveled finding.

• Wrapping a schema in a null oneOf is one INFO finding. It used to read as false breaking errors: the wrapped enum reported all its values as removed, plus type and oneOf noise. oasdiff now proves the wrapped schema is equivalent to the original and reports became-nullable.
• Unwrapping reports became-not-nullable. Breaking on the request side (the request no longer accepts null), informational on the response side, with new response verdicts that also cover forms that previously reported nothing.
• Parameters are covered. A parameter flipping between type: [string, "null"] and type: string was silent in both directions, although the removal direction is breaking. New parameter and parameter-property verdicts close it.
• A new nullability guide explains the model, when a nullability change is breaking, and the deliberate limits.

Available in oasdiff v1.23.0 and oasdiff-action v0.1.6.

breaking and changelog now tell you exactly where each change happened in your spec.

• Precise source locations for every change. Each change carries the file, line, and column it came from, now including security, stability, sunset, and x-extensible-enum changes, down to the exact field or removed value. In --format json or yaml output you can jump straight to it.
• OpenAPI 3.1 nullable arrays no longer break --flatten-allof. A multi-type array like type: [integer, "null"] inside an allOf no longer fails with a type-conflict error when there is no real conflict.
• A published output schema. The new oasdiff schema command prints a JSON Schema for the breaking / changelog json output, so CI tooling can validate or type the results.

Available in oasdiff-action v0.1.5, running oasdiff v1.22.0.

oasdiff v1.21.0 fills in several response-side checks, fixes a crash, and rewrites the type change messages to read in plain English.

• No more crash on schema-less media types. Comparing a response that gains or loses its schema (content: { application/json: {} } to a typed body, or back) no longer panics; the change is reported instead.
• Response type widening vs narrowing. A response type that narrows (number to integer) is now flagged as a safe change, and one that widens (integer to number) as a breaking one, instead of a single generic "type changed".
• More response-side changes detected. A media type schema added or removed where there was none, and an added response header, are now reported.
• Clearer messages. Type and format change messages now name the dimension that changed, fold away empty formats, show array item types (array<string>), and say "widened" / "narrowed" instead of "generalized" / "specialized".

Available in oasdiff v1.21.0.

oasdiff v1.20.1 sharpens the diff and fixes how empty results are formatted.

• No phantom security changes. When an operation allows an OR of OAuth2 scopes by listing the same scheme more than once (- petstore_auth: [read] / - petstore_auth: [write]), the diff no longer invents a scope add or remove. It was even firing when comparing a spec against an identical copy. The diff now also identifies exactly which requirement changed.
• Fewer false positives. A request property wrapped in oneOf is no longer reported as removed.
• Valid empty output in every format. A clean spec or an empty diff now renders a valid empty document ({} or [] for JSON and YAML, and a clear "No changes detected" line for text), instead of empty or malformed output.

Available in oasdiff v1.20.1.

The Pro review that the changelog action posts on your pull requests is now end-to-end encrypted. With an oasdiff-token set, the action encrypts your specs client-side in CI before upload, and the decryption key travels only in the review link's URL fragment, which browsers never send to a server. The review renders for your team, but oasdiff cannot read your spec content.

• Approve or reject each change on the PR. The action posts a comment linking to a side-by-side review where your team approves or rejects every change. The oasdiff commit status gates merge until all breaking changes are approved.
• Nothing readable stored at rest. Only ciphertext is uploaded; the key stays in the link, so a stored review is a blob we cannot open.
• A clear message when a trial or subscription ends. Instead of an opaque failed run, the action now says your plan has expired and links you to renew, without breaking your build.

Available in oasdiff-action v0.1.3, running oasdiff v1.20.0. See setup.

oasdiff now runs as an MCP server, so Claude, Cursor, and other AI assistants can call it directly. Ask "does this change break the API?" and your assistant runs oasdiff on the two specs and reads back the result.

It's hosted and remote (Streamable HTTP, no install, no API key): point your client at https://api.oasdiff.com/mcp. Four tools are available: breaking changes, changelog, diff, and validate. See Use oasdiff from your AI assistant for the one-line setup for Claude Code and Cursor.

A round of fixes to the free side-by-side review that the breaking and changelog actions post on every pull request with changes:

• Get the review as a pull-request comment. When the action runs without a github-token, it now tells you to add one (with pull-requests: write) so the review link is posted as a PR comment instead of only landing in the job summary. See the setup.
• No review comment on an unchanged PR. With format: json, yaml, or markup, a pull request with no API changes could still get a review comment. Detection no longer depends on the output format, so a clean PR stays clean.
• A clear message in composed mode. With composed: true the review compares exactly two specs and isn't available; the action now says so once instead of printing a confusing "couldn't upload" warning.
• A .oasdiff.yaml in your repo can't break the review. The action pins the settings the review depends on, so a config file can't silently drop the review link or the inline annotations.

oasdiff --open is additive too: an upload hiccup never changes your fail-on result or the command's exit code.

Available in oasdiff-action v0.1.1, running oasdiff v1.19.1.

oasdiff's side-by-side API change review is now free for everyone. See exactly what changed between two API specs, rendered as a full visual diff.

Point it at any two versions of your spec, wherever they live, and open the review three ways:

• Command line: oasdiff changelog --open (or breaking --open)
• Free GitHub Action: the breaking and changelog actions link straight to the review on every pull request with changes
• Online diff tool: the "Share as a side-by-side review" button

Two things you'll use it for:

1. Understand a change in context. Every change is highlighted inside its operation or schema in the full diff, so you see not just what changed but where.
2. Share it for review. Send the link to teammates and anyone can open it, with no install and no account. Each change also has its own link, so you can point someone straight at the one you mean.

Your review stays private. What we store is an encrypted blob we cannot read: the one-time key that unlocks it lives only in the review link (the part after the #) and never reaches our servers. From the command line and the GitHub Action it goes further, since the comparison is computed and encrypted on your own machine, so the specs never leave it in the clear. Links expire after 7 days.

Need to act on a review, not just read it? oasdiff Pro lets reviewers approve or reject each change, keeps the merge blocked until every breaking change has been reviewed, and records who approved what, right on the pull request. Try Pro.

Available in oasdiff v1.19.0 and the oasdiff GitHub Action v0.1.0.

The diff tool's text output now reads like the CLI: colorized by severity, with the columns aligned. And the copy button gives you clean, paste-ready text, no color codes, tabs expanded to spaces, so a breaking-changes or changelog report drops straight into a PR comment, ticket, or doc and still lines up.

Try it on the diff tool: pick Breaking, Changelog, or Validate, choose the Text format, and copy.

Compared two specs in the diff tool? You can now open them as a side-by-side review and share it with your team, instead of copying markdown or HTML into a message.

Click "Share as a side-by-side review" and sign in with GitHub. You land on the review page with the full change list, and each change has a "Copy link to this change" button, so you can point a teammate at one specific change, not just the whole diff. Anyone with a link can open it, no install and no account needed on their end. Links last 7 days.

When you compare two git revisions, say oasdiff changelog main:openapi.yaml release:openapi.yaml, and one of the commits is not in your local clone yet, oasdiff used to stop and print the git fetch command for you to run. Add --fetch and oasdiff fetches the missing revisions from origin itself, then runs the comparison in one step. Without the flag it stays read-only, so you decide when your repository is touched.

Available in oasdiff v1.18.5.

The breaking, changelog, and diff actions could fail unexpectedly on a few specific spec changes, for example an array property that dropped its items, or a removed not / if / then / else schema. Those comparisons now run cleanly. The breaking and changelog actions also catch property changes nested inside a not schema, which were skipped before.

Available in oasdiff-action v0.0.57.

When the free oasdiff GitHub Action finds breaking changes, the Checks summary now links straight to a shareable side-by-side review. And when you run the review command locally, oasdiff now tells you the exact git fetch to run if a commit isn't in your clone yet, instead of a cryptic git error.

Available in oasdiff v1.18.4 and oasdiff-action v0.0.56.

Reviewing breaking changes is a team decision, so it should be easy to pull the right person in.

Every breaking change on a review now has an Ask a teammate to review action. It creates a single-use invite and copies a link you can paste anywhere (Slack, a PR comment, email). When your teammate opens it, they sign in, join your team, and land directly on that change, ready to approve or reject it. Asking for a second opinion is the invite, so they arrive able to act instead of stuck on a read-only page.

And when someone who is not yet on your team opens a review, they can ask to join. You get an email and a request in your account settings; approve it and they are sent an invite automatically.

Setting up oasdiff Pro has a few moving parts: the GitHub App, the repository token, the workflow file, and your spec paths. Until now the first real signal that it all fit together was an actual pull request.

You can now check the whole chain on demand. Open your repository's Actions tab, choose the oasdiff workflow, and click Run workflow. It runs a read-only check (no pull request, no comment, no commit status) and reports a checklist: the workflow ran, the token authenticated, the oasdiff GitHub App is installed, your spec files resolved, and your GitHub sign-in can read the spec.

Results appear both in the run's summary and on your setup page, so you can spot and fix a missing step before it matters on a real PR.

The oasdiff GitHub Actions now default to allow-external-refs: false. Because CI commonly runs on pull requests from forks, external $refs in a spec are no longer fetched or resolved by default — the safe choice for untrusted input.

Specs loaded the recommended way are unaffected: with the git-ref form (base: 'origin/main:openapi.yaml'), in-repository $refs — single- or multi-file — resolve via git show, not as external references.

If your spec references an external URL, or you load split multi-file specs by plain file path instead of the git-ref form, opt back in with the new allow-external-refs input (available on all five actions):

- uses: oasdiff/oasdiff-action/breaking@v0.0.51
  with:
    base: 'origin/${{ github.base_ref }}:openapi.yaml'
    revision: 'HEAD:openapi.yaml'
    allow-external-refs: true

Failures now also surface as annotations on the Checks tab, with a one-line hint when a blocked external $ref is the cause. Available in oasdiff-action v0.0.51 (runs on oasdiff v1.18.1).

Security: this change also addresses GHSA-fhj3-7267-7vv5. Before v0.0.51, the permissive default could resolve attacker-controlled $refs on fork pull requests (SSRF, and disclosure of structured files on the runner). The base-image fix is GHSA-2jcc-mxv7-p3f9, in oasdiff v1.18.1. If you pin an older action version, upgrade to v0.0.51.

oasdiff changelog and oasdiff breaking now accept an --open flag. After printing the changelog in your terminal, the CLI uploads the two specs to oasdiff.com and opens a side-by-side review in your browser — the same view paying customers see, with the approve / reject buttons present (locked on the free tier) and the diff anchored at each breaking change.

oasdiff changelog HEAD~1:openapi.yaml HEAD:openapi.yaml --open

The resulting URL is unguessable and works for 7 days. Paste it into a PR comment or your team's Slack and reviewers can open it directly — no CLI install required on their side, no GitHub OAuth approval. First run prompts for GitHub sign-in (minimal scopes, no repo access) and stores a token locally; subsequent runs skip it.

Works against any spec you can git show — public or private. See /docs/free-review for the full walkthrough.

New oasdiff git-diff-driver subcommand wires oasdiff into git as an external diff driver, so git log --patch --ext-diff and git diff render a human-readable OpenAPI changelog inline instead of a raw YAML text diff.

Two config lines:

git config diff.oasdiff.command "oasdiff git-diff-driver"
echo "openapi.yaml diff=oasdiff" >> .gitattributes

Then:

git log --patch --ext-diff -- openapi.yaml

For each commit that touched the spec, you'll see the same human-readable changelog oasdiff changelog would emit, instead of YAML hunks. Added (root commit) and removed files are handled inline; mode-only changes are skipped.

Inspired by Jamie Tanna's post on using oasdiff as a git diff driver via a bash wrapper. The wrapper is no longer needed. Available in oasdiff v1.17.0.

HTTP header names are case-insensitive per RFC 9110, but the diff was treating Content-Type and content-type as different headers. Renaming a header to a different case in your spec produced spurious "header removed + header added" findings.

That's now the default behaviour. To get the strict, case-sensitive comparison back:

• On /diff: open Comparison options and uncheck Case-insensitive headers.
• On the CLI / GitHub Action: pass --case-insensitive-headers=false.

The /diff calculator now exposes the same fine-tuning knobs the CLI has, under a new Comparison options disclosure:

• Match inline / $ref subschemas — recognise refactors that pull an inline schema into a named component
• Case-insensitive headers — RFC 9110 default
• Flatten allOf — merge allOf subschemas before diffing
• Flatten path-level parameters — merge path-level params with operation params
• Auto-upgrade to latest 3.x — canonicalise 3.0 specs before diffing (useful for cross-version comparisons)
• Include path parameter names in matching — treat /pets/{id} and /pets/{petId} as different paths

Defaults match the CLI's, so the result on the page mirrors what oasdiff diff produces locally unless you toggle something.

Refactors that pull an inline subschema into components/schemas and reference it via $ref are now recognised as the same branch inside anyOf / oneOf unions. The compared specs may look different on paper, but if they produce the same wire contract the diff reflects that.

This sits in the diff engine itself, so the Diff, Breaking, and Changelog modes on /diff — and the matching CLI subcommands — all benefit consistently.

A new Validate mode is available on /diff. Drop a single spec, get every OpenAPI and JSON Schema violation with its file and line.

The same capability is also in the CLI:

oasdiff validate spec.yaml

and as a GitHub Action — oasdiff/oasdiff-action/validate — so you can fail a workflow on invalid specs without writing your own validator.

The /review page now guides visitors through the common access cases — missing repository permission, SAML authorisation needed, wrong file path — directly on the page:

• A diagnostic panel showing the signed-in user, the repo, each spec file with its status, and a Reference ID for support.
• An ordered recovery checklist filtered to the steps that match the situation.
• A "Contact us" option that pre-fills an email with the diagnostics and Reference ID, so anything that does reach us arrives with everything we need.

Inaccessible $refs route through the same surface, so a referenced fragment uses the same recovery flow as the top-level spec.

The /review link that the free breaking and changelog actions emit into the GitHub Step Summary used to encode the branch name of the base (typically main). If main advanced past a renamed or moved spec file before someone clicked the link, the link 404'd.

The action now writes the immutable base commit SHA into the URL. Once the link is in the Step Summary, it points at the same content forever, even as the base branch moves on.

The pr-comment action now renders cleanly on repositories with substantial API surfaces — changelogs of several megabytes are handled the same as small ones, with no special configuration needed.

On the service side, when a change table would exceed GitHub's 65 KB issue-comment limit the action posts a summary (severity counts) plus a prominent link to the full review page, which has no size cap.

You can now compare an OpenAPI 3.0 spec against an OpenAPI 3.1 spec without converting them by hand.

On /diff: open Comparison options and turn on Auto-upgrade to latest 3.x. The older spec is canonicalised to 3.1 before the comparison runs.

On the CLI / GitHub Action: pass --auto-upgrade on diff, breaking, or changelog. A standalone oasdiff upgrade subcommand is also available if you want the canonicalised spec out for some other use.

Repeated flags can now live in a config file checked into the repo:

# .oasdiff.yaml
match-inline-refs: true
case-insensitive-headers: true
fail-on: error
exclude-elements:
  - description
  - examples

The CLI picks it up automatically when you're in the directory, or you can point at one explicitly via --config or the OASDIFF_CONFIG environment variable. The free GitHub Actions read the same file, so one .oasdiff.yaml configures both your local runs and your CI.

After the free breaking or changelog actions run on a PR, the GitHub Step Summary now includes a clickable link to a full side-by-side preview of the change:

📋 Review & approve these breaking changes → https://oasdiff.com/review?...

Click it to see the diff with inline annotations and the changes laid out next to each other. Useful when the CI annotation tells you that something broke and you want to see exactly what changed before approving the PR — no install needed.

OpenAPI 3.1 support is out of beta. Diff, Breaking, and Changelog all work natively against 3.1 specs, with full handling of the new keywords (prefixItems, dependentSchemas, dependentRequired, if/then/else, contains/minContains/maxContains) and the new type-array nullability shape.

/diff, the GitHub Actions, and the Pro /review page all read 3.0 and 3.1 transparently. If you have a 3.0 spec to migrate, /docs/openapi-31-migration includes an interactive widget that takes your 3.0 spec and gives you the 3.1 equivalent to copy.