Free OpenAPI diff & breaking-change checker

Paste or upload two OpenAPI specs (JSON or YAML) and instantly see breaking changes, additions, and modifications. No sign-up.

Loading the diff tool…

How the OpenAPI diff works

  1. Step 1

    Add your two specs

    Paste or upload a base spec (your old / stable version) and a target spec (the new / changed version). JSON or YAML both work.

  2. Step 2

    Compare

    SpecShield walks every path, parameter, and request/response schema in both specs and classifies what changed.

  3. Step 3

    Review the impact

    Results are grouped into breaking changes, additions, and modifications, so you can see at a glance whether the new version is safe to ship.

What counts as a breaking change?

Breaking changes (examples)

  • ✗Removing an endpoint, operation, or response field
  • ✗Making a previously optional parameter or property required
  • ✗Narrowing a type, format, or enum (e.g. removing an allowed value)
  • ✗Renaming a field or changing a response shape consumers depend on
  • ✗Adding a new required request parameter

Usually safe (additive)

  • ✓Adding a new endpoint or operation
  • ✓Adding a new optional parameter
  • ✓Adding a new field to a response body
  • ✓Documenting an existing field more precisely (no shape change)

Frequently asked questions

What is an OpenAPI diff?
An OpenAPI diff compares two versions of an OpenAPI (Swagger) specification and reports exactly what changed between them — which endpoints, parameters, and schemas were added, modified, or removed — so you can tell whether the new version breaks existing API consumers. SpecShield runs this diff free in the browser, and on every pull request via its GitHub App.
What counts as a breaking change in an API?
A breaking change is any change that can stop an existing client from working: removing an endpoint or field, making an optional parameter required, narrowing a type or enum, or changing a response shape consumers rely on. Additive changes like new endpoints or new optional fields are usually safe. SpecShield classifies each change into breaking, additive or modified, and can block the merge when a breaking change would affect a consumer you have registered.
Is this OpenAPI diff tool free?
Yes. The web diff is completely free and needs no sign-up or installation. A free SpecShield account adds saved compare history, GitHub pull-request checks, a CLI and GitHub Action, and a can-i-deploy gate.
Do I need to sign up or install anything?
No. Paste or upload two specs into the SpecShield web diff and get results instantly — no account, no download, no credit card. A free SpecShield account is only needed for saved history, CI checks and the can-i-deploy gate.
Does it work with Swagger and YAML?
Yes. SpecShield compares OpenAPI specifications (the format formerly known as Swagger) in either JSON or YAML, including OpenAPI 3.0 and 3.1.
Is my API spec stored or shared?
No. Specs are compared in the request and not persisted — SpecShield compares them, shows the results, and forgets them.
How is this different from oasdiff or PactFlow?
The diff itself does the same breaking-change detection job. What SpecShield adds is everything after detection: a hosted can-i-deploy deploy gate, GitHub PR checks, and team history — contract compatibility testing without a Pact broker or DSL.

Keep reading