Dev.to Security ๐Ÿ” Cybersecurity ๐Ÿ‘ 0 ๐Ÿ“– 7 min read

oasdiff vs SpecShield (2026): which OpenAPI breaking-change tool should you use?

Disclosure first: I build SpecShield. This is a comparison written by the author of one of the two tools, so read it with that in mind. I've tried to make it the post I'd want to find if I were choosing โ€” including the p

Disclosure first: I build SpecShield. This is a comparison written by the author of one of the two tools, so read it with that in mind. I've tried to make it the post I'd want to find if I were choosing โ€” including the parts where oasdiff is simply better. Every oasdiff claim below links to or comes from its own docs and pricing page, as of November 2026.

The short answer

  • You want to know whether a PR breaks the spec: use oasdiff. It's free, Apache-2.0, and the most thorough OpenAPI diff engine there is.
  • You want the CI check that decides whether the PR merges โ€” with expiring waivers, usage data from real traffic, and security regressions blocked too โ€” that's the part SpecShield is built for.
  • Many teams should run both. They don't conflict.
oasdiff SpecShield
License / price Apache-2.0 CLI, free. Hosted Pro $100/mo (5 reviewers, 5 repos) Free CLI tier. Team $89/mo (up to 10 users)
Breaking-change catalog 784 kinds of change (359 breaking, 23 warning, 402 info) Smaller. Nullability, constraint and enum checks run only on the hosted engine
Spec versions OpenAPI 3.0, plus 3.1 and 3.2 (what's supported) OpenAPI 3.0, 3.1 and Swagger 2.0
Compare against a git ref Yes (base can be a branch, tag or commit) gate picks the merge base automatically
Multi-file / gateway specs Composed mode No
Accepting a known break --err-ignore / --warn-ignore text files Waivers with an owner, reason and expiry
Approval in the PR Pro: approve/reject per change in a PR comment GitHub App check run + PR comment
"Who does this break?" No Yes, from your access logs
Security regressions Detected, but graded by client compatibility (see below) Graded by risk; blocks auth removal, dropped scopes, leaked secrets
Proof / fix No prove (the request that breaks), fix (non-breaking rewrite)
Embed in Go / MCP server Yes / yes No / yes

The rest of the post explains the rows that matter.

Where oasdiff wins

Depth of the diff. oasdiff's published catalog lists 784 kinds of API change, each with a level: 359 breaking, 23 warning, 402 informational. It handles the hard cases most diff tools quietly get wrong: allOf flattening, the three equivalent ways of writing nullable, renamed path parameters, path prefixes that moved, header-name casing.

SpecShield's local engine covers the common breaking changes (removed endpoints and fields, new required inputs, type changes), but some checks โ€” nullability, constraints and enum additions โ€” only run on the hosted engine. If raw diff coverage is your requirement, oasdiff is ahead and I don't expect that to change soon.

Ecosystem and maturity. Go library you can embed, Docker image, Homebrew, pre-commit hook, a git diff driver so git log -p shows an API changelog, stability levels (draft/alpha/beta/stable), a --fail-on MISSING-VERSION-BUMP check, changelog templates, and localization. Around 1,450 GitHub stars and a release (v1.38.0) on 14 November 2026. It's actively maintained.

Cost. The CLI, the GitHub Action and the shareable review page are free with no account. You only pay ($100/month) for the hosted approval workflow.

If your question is "did this PR break the contract?", stop here and install oasdiff:

oasdiff breaking --fail-on ERR base.yaml revision.yaml

Where they differ: "breaking" isn't the same as "dangerous"

This is the most useful thing I learned building the security side of SpecShield, and it applies even if you never use it.

oasdiff classifies every change from the point of view of existing clients: will a client that worked yesterday still work today? That's exactly the right question for breaking changes. But look at what it means for security changes, straight from oasdiff's own catalog:

oasdiff check Level
api-security-anonymous-access-added โ€” endpoint now accepts unauthenticated requests Info
api-security-scope-removed โ€” scope deleted from an endpoint's security scheme Info
api-security-scope-added โ€” scope added to an endpoint's security scheme Breaking

That's correct for compatibility. If an endpoint stops requiring a token, every existing client keeps working, so it's not breaking. Adding a scope locks some clients out, so it is.

It's also the exact inverse of what a security reviewer cares about. The change that opens your API to anonymous callers is the info one.

Here's a small PR against a two-endpoint spec. It makes GET /orders/{orderId} public, drops the admin scope from POST /refunds, adds a client_secret field to the order response, and adds a public GET /exports. A breaking-change diff (SpecShield's compare) sees nothing wrong:

  0 breaking  2 additions  0 modifications  0 warnings

  + Field "responses.200.client_secret" was added to GET /orders/{orderId}
  + GET /exports was added

The same PR through the gate with --security:

$ specshield gate openapi.yaml --security

  โœ– 3 security regressions block this change

  โ— Security: GET /orders/{orderId} no longer requires authentication (was bearer) โ€” anyone can call it
  โ— Security: new field "client_secret" in a public response looks like a credential
  โ— Security: POST /refunds no longer requires scope admin on oauth

  Security review (1, not blocking)
  โ–ฒ Security: new endpoint GET /exports is public (security: [])

(That's real output, trimmed of the waiver hints. I didn't run oasdiff on this example, so I won't claim exactly which of its checks fire; the levels above are from its catalog.)

To be fair to oasdiff: you can promote those checks yourself. Its --severity-levels file lets you set api-security-anonymous-access-added err, and then a public endpoint fails the build. If you only use oasdiff, I'd strongly recommend doing that today. What it won't do is look at response fields for credentials or personal data, or rank a downgrade from bearer to an API key in the query string as a weakening rather than a change.

Where they differ: who does it break?

A diff tells you what changed. It can't tell you whether anyone uses it.

SpecShield reads the access logs you already have (nginx, ALB, JSON, Kubernetes audit logs) and turns them into a usage summary โ€” counts per endpoint and client, nothing more; raw logs never leave the machine:

specshield usage import /var/log/nginx/access.log* --spec openapi.yaml
specshield gate openapi.yaml --usage usage.json

Then each breaking change says who it breaks, and a removal no client has called in the window stops failing the build:

  โ— DELETE /orders/{orderId}/receipt method was removed
    โ†ณ impact: 1 client ยท 134 calls ยท last seen 72 min ago
        MyShop-iOS/5.2  100% of calls  134 ยท last seen 72 min ago

  โœ”  BREAKING BUT UNUSED โ€” safe to ship
  โ—‹ GET /legacy-report was removed

oasdiff has nothing like this; it's not what oasdiff is for. If you don't have access logs, this row doesn't matter to you.

Where they differ: accepting a break

Both tools let you accept a known break. The difference is what happens six months later.

oasdiff uses ignore files โ€” one line per accepted change, passed with --err-ignore / --warn-ignore. Simple, and it works.

SpecShield waivers need an owner, a reason and an expiry (90 days at most by default), and they live in the repo next to the change they accept:

specshield waivers add response-field-removed --operation "GET /pets/{id}" --field legacy_id \
  --owner @alice --reason "Mobile 4.2+ stopped reading it" --days 30

When it expires, the change blocks again and the output says whose waiver lapsed. The point is that a gate with permanent ignores slowly stops being a gate.

oasdiff's paid Pro tier solves a related problem differently: every change gets approve/reject in a PR comment, with an audit trail of who approved what. If per-change human approval is what your team wants, that's a good model.

Things only SpecShield does (and their limits)

  • prove โ€” for every breaking change, generates the request that worked against the old spec and fails against the new one, checked against both specs. With --against <url> it sends it to a running build. Useful when someone asks "is that actually breaking?"
  • fix โ€” rewrites the new spec into a non-breaking version (expand-and-contract), and verifies each edit with the diff engine.
  • audit โ€” checks the spec against the OWASP API Security Top 10, and compares access logs with the spec to find shadow endpoints, old /v1 routes still answering, and files like /.env returning 200.

None of this is runtime security testing. SpecShield reads what the spec declares and what your logs recorded. It doesn't attack a running service.

Pricing, side by side

oasdiff SpecShield
Free CLI, GitHub Action, shareable review page, no account CLI (compare, gate, audit, usage), 1 GitHub App PR check
Paid Pro $100/mo โ€” approval workflow, audit trail, merge gate; 5 reviewers, 5 repos Team $89/mo ($75/mo annual) โ€” up to 10 users; consumer registry, can-i-deploy, governance gate, dashboard
Enterprise Custom; specs never uploaded Custom; SSO, on-prem on request

Prices from oasdiff.com/pricing and specshield.io/pricing, November 2026.

What I'd recommend

  • Solo dev or small team, one spec: oasdiff, free. Add --severity-levels to promote the anonymous-access check.
  • Several teams, a gate that has to stay on: SpecShield's gate, for the expiring waivers and shadow mode before you turn on blocking.
  • You have access logs and keep arguing about whether a removal is safe: SpecShield with --usage.
  • You want security changes blocked in the same PR check: specshield gate --security.
  • Already happy with oasdiff? Keep it. Add npx specshield gate openapi.yaml --security --shadow next to it for two weeks and see whether it finds anything oasdiff didn't. If it doesn't, you've lost nothing.

CLI: npm i -g specshield ยท npm ยท specshield.io

If you've hit a case where oasdiff and SpecShield disagree on whether something is breaking, I'd genuinely like to see it โ€” post it in the comments.

๐Ÿ“ฐ Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes โ€” full credit and traffic to the original publisher.