What's new in oasdiff

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.