When a new version of an API is released, the question every consumer asks is the same: what changed, and will it break my code? The release notes may list the headline changes, but they rarely list all of them. A renamed field, a newly required parameter, a response code that disappeared, a type that changed from integer to string — any of these can break a client, and any of them can hide in a specification diff that nobody read carefully. Comparing the two specifications directly, rather than trusting the changelog, is the reliable way to answer the question.
The OpenAPI Specification Diff Checker performs that comparison in your browser. You provide the old specification and the new one, and it reports the differences: added and removed paths, changed operations, altered parameters, modified request and response schemas, and changed security requirements. The specifications stay on your device, which matters when they describe internal or unreleased APIs.
How the tool works
A diff checker does not compare specifications as raw text, because text comparison drowns the meaningful changes in formatting noise: a reordered key, a reworded description, or a reformatted file would appear as hundreds of changed lines. Instead, it parses both specifications into their structure — paths, operations, parameters, schemas — and compares them semantically. A path present in the new specification but absent in the old is an addition. An operation whose response schema gained a field is a modification, and the checker can say which field and whether it is required. A parameter that moved from optional to required is flagged as a change in its required status, not merely as a changed line.
The results are best read in order of risk. Breaking changes come first: anything that can break an existing client. A removed endpoint, a removed field from a response, a newly required request field, a changed field type, and a removed response code are all breaking, because code written against the old specification may fail against the new one. Non-breaking changes come next: added endpoints, added optional fields, added response codes, and relaxed constraints, which old clients can generally ignore. Editorial changes come last: description wording, example values, and documentation text, which affect no client at all. Reading the diff in that order keeps the review focused on what can actually break, rather than on the volume of changes.
Versioning context helps the review. If the new version is a major version, breaking changes are expected, and the reviewer's job is to catalogue them completely so consumers can migrate. If it is a minor or patch version, breaking changes are not expected, and any that appear deserve a challenge: either the version number is wrong, or the change needs to be reverted or made backward-compatible. The diff gives you the evidence for that conversation; without it, the conversation is guesswork.
A worked example
Suppose version 1 of an API has 12 endpoints. Version 2 adds 3 new endpoints and removes 1 old one. The endpoint count in version 2 is therefore 12 + 3 − 1 = 14. A diff checker would report the 3 additions, the 1 removal, and any modifications to the 11 endpoints that exist in both versions. That arithmetic is a useful sanity check: if the checker reports 14 endpoints in the new specification but you count a different number in the file, something is off — perhaps a path is defined twice, or a path with no operations is being counted differently.
Now look at the modifications in detail. Imagine the diff reports that the GET /users/{id} response gained an optional nickname field, that the POST /users request made email required where it was previously optional, and that the GET /orders response removed the discount field. Those three changes have very different risk. The added optional field is safe: old clients ignore fields they do not know. The newly required email is breaking for any client that creates users without an email, and those clients will start receiving validation errors. The removed discount field is breaking for any client that displays or totals discounts. A reviewer reading this diff would approve the first change without comment, flag the second for a migration note, and flag the third as a decision that needs an owner: either restore the field, or confirm that no consumer depends on it.
A good review habit is to check the diff against the changelog. If the changelog mentions the new endpoints and the required email, but says nothing about the removed discount field, the changelog is incomplete, and the diff has just caught a change that would otherwise have reached consumers unannounced. That catch is the diff checker's main value: it finds the changes nobody thought to mention.
Common mistakes
The most common mistake is reviewing only the changelog and skipping the diff. Changelogs are written by humans, from memory, under deadline pressure, and they omit things. A diff is computed from the actual specifications, and it omits nothing. For any version that consumers depend on, the diff is the review, and the changelog is a summary of it — not a substitute for it.
The second mistake is treating all changes as equal. A diff with two hundred lines of description rewording and one removed field is not a two-hundred-line problem; it is a one-field problem, and the rewording is noise. Sort or filter the diff by risk, and spend your attention on breaking changes first. If the tool does not sort by risk, read it with that priority in mind and set the editorial changes aside.
The third mistake is diffing the wrong pair of specifications. Comparing the new version against a draft, or against a version that was never released, produces a misleading list of changes. Always confirm which versions you are comparing: the currently released specification and the proposed one. If either file is a local copy, verify it matches the published version before drawing conclusions from the diff.
The fourth mistake is forgetting that a specification diff shows the contract, not the implementation. An endpoint can be added to the specification without being implemented, or removed from the implementation without being removed from the specification. The diff tells you what the contract says changed; testing against the deployed API tells you what actually changed. Use both, and do not let either replace the other.
Honest limitations
A diff checker reports structural differences; it does not judge them. It cannot tell you whether removing a field is acceptable, whether a new requirement is justified, or whether consumers actually depend on the changed behaviour — those are product and communication decisions that need human judgement and, ideally, knowledge of who calls the API. It also cannot detect behavioural changes that leave the specification untouched: a field that still exists but is now computed differently, a rate limit that tightened, or a response that became slower. Those changes are invisible to a specification diff by definition. Finally, specifications in different formats or versions — JSON versus YAML, OpenAPI 3.0 versus 3.1 — may need normalisation before comparison, and a checker that does not normalise may report formatting differences as content changes. Check the tool's handling of format differences before trusting a large diff.
Closing
Diff the specifications, read breaking changes first, check the result against the changelog, and challenge any breaking change in a minor version. That review is the cheapest moment to catch a breaking change — far cheaper than discovering it from a consumer's bug report. To check a specification's security properties alongside its changes, use the OpenAPI Security Auditor, and to compare JSON data structurally, use JSON Studio. For comparing JSON documents in depth, see How to Compare Two JSON Versions Structurally.