What's new in oasdiff

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.