← OpenAPI Breaking Change Check
OpenAPI Breaking Change Check vs. oasdiff
Overlapping ground, very different depth and packaging. oasdiff is an installable, open-source Go CLI with 755 documented change rules reaching deep into request and response body schemas. This tool checks 12 of the most common operation, parameter, and request-body changes, on JSON you paste, free, with nothing to install and no network call of its own.
What each tool is for
oasdiff (github.com/oasdiff/oasdiff) is an open-source,
Apache-2.0-licensed CLI written in Go, installed with go install
github.com/oasdiff/oasdiff@latest, its Homebrew formula, a Docker image, or a pre-built
binary from its releases page. It reads OpenAPI 3.0, 3.1, or 3.2 documents in either YAML or JSON,
and its oasdiff breaking base.yaml revision.yaml command exits 0 when no breaking
change is found and 1 when one is. Per its own documentation it recognizes 755 distinct kinds of
change, breaking and non-breaking together -- including differences buried inside request and
response body JSON Schemas, well past the operation/parameter level -- and can print the result as
text, JSON, YAML, Markdown, or HTML. It also ships an official GitHub Action
(oasdiff/oasdiff-action) that runs the same check on every pull request and posts a
side-by-side review comment.
This checker does a narrower slice of that and nothing else: you paste two OpenAPI
3.0/3.1 JSON documents, and it lists every operation removed or added, every parameter that
is new, removed, or newly required, every parameter type change or enum-value change, and every
request body that gained or lost its required flag -- 12 change kinds in total. It does
not read YAML, and it does not look inside a request or response body's schema beyond that one
required flag. It runs entirely in your browser, needs no install, and makes no network call of any
kind under any configuration.
| Question | Where to answer it |
|---|---|
| I need every documented kind of change, including ones buried inside a request or response body's JSON Schema. | oasdiff -- 755 documented change rules cover that depth; this tool's 12 do not. |
| My spec is in YAML, not JSON. | oasdiff reads YAML directly. This tool reads JSON only -- convert first. |
| I want an automatic review comment posted on every pull request that touches the spec. | oasdiff's own GitHub Action is built for exactly that; this tool has none. |
| I just want to know if the two JSON files in front of me have an operation, parameter, or request-body change, right now, with nothing to install. | This checker -- paste both, click Check, get the table. |
| I want this specific check to fail my CI automatically. | Either: oasdiff's own exit code (0/1) in a CI step, or this tool's --fail-on-breaking for the narrower question specifically. |
| I don't want to install a Go binary or add a new GitHub Action just to check one pair of files. | This checker -- it is a page, not a package. |
The two are complementary, not competing: a team can run oasdiff in CI for full-depth coverage across every pull request and still reach for this tool the moment the question is "does this one pasted pair of JSON files have a common-case breaking change" without installing anything.
Common questions
Should I use this checker or oasdiff?
They overlap on the common cases -- a removed operation, a parameter that became required, a narrowed type -- and differ sharply in depth and packaging. oasdiff is an open-source, Apache-2.0-licensed Go CLI (installed with go install, Homebrew, Docker, or a pre-built binary from its releases page) that reads OpenAPI 3.0, 3.1, or 3.2 documents in YAML or JSON and, per its own documentation, recognizes 755 distinct kinds of change -- breaking and non-breaking together -- including differences buried inside request and response body JSON Schemas. This tool checks 12 of the most common operation, parameter, and request-body-flag changes only, runs entirely in your browser on JSON you paste, and cannot read YAML or diff a body schema. If you need the deepest available diff, YAML support, or a GitHub Action that reviews every pull request automatically, oasdiff is the right tool. If you want a fast, no-install answer to the common-case question on two JSON files you already have open, this is the narrower tool for that.
Does oasdiff catch more than this tool does?
Yes, considerably more. oasdiff's own documentation lists 755 distinct recognized changes, spanning far past operations and parameters into request and response body schemas, headers, security requirements, and more -- ground this tool's shallow structural comparison does not cover at all. This tool implements 12 change kinds: an operation removed or added, a parameter that is new, removed, or newly required, a parameter's declared type changed, an enum value added or removed, a parameter newly or no-longer restricted to an enum, and a request body's required flag changing either direction. Every one of those also appears in oasdiff's catalogue; the difference is that oasdiff's catalogue keeps going well beyond them.
Why use a narrower browser tool if oasdiff already covers deep schema changes?
Two reasons this tool exists alongside it. First, oasdiff is a Go binary you install and then point at files on disk (or wire into CI via its GitHub Action); this tool is a page you open and paste two JSON documents into, which is faster when you just want one quick answer and have not set up a CLI or don't want to install a new binary for a single check. Second, a report spanning 755 possible change kinds is a different shape of answer than a short table naming exactly which operation, parameter, or request-body flag changed and how -- when the question is only the common-case one, this tool's narrower output is faster to read.
Does this tool read YAML specs the way oasdiff does?
No. oasdiff reads OpenAPI documents in either YAML or JSON. This tool -- both the browser page and the CLI script -- reads OpenAPI 3.0.x/3.1.x JSON only, and explicitly rejects a Swagger 2.0 document rather than misreading it. If your spec is YAML, convert it to JSON first with any OpenAPI tool's own export or a YAML-to-JSON converter before pasting it here, or use oasdiff directly on the YAML file.
Is this page affiliated with oasdiff or its maintainers?
No. This site is not affiliated with, endorsed by, or sponsored by oasdiff or its maintainers. oasdiff is an independent open-source project, named here only to describe what this checker is and is not, using facts drawn from its own public documentation at oasdiff.com and its source repository at github.com/oasdiff/oasdiff.