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/v1routes still answering, and files like/.envreturning 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-levelsto 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 --shadownext 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.
Top comments (0)