The obvious first move when reviewing a new API version is diff old-spec.json new-spec.json, or scanning a pull request that touches the OpenAPI file. Both work, and both bury the one change that would actually break a client under everything else that changed for reasons nobody needs to review twice.
Reading the raw diff is correct and complete for reviewing every difference between two JSON documents: reordered keys, reworded descriptions, new examples, tag changes, all of it. Its limit here is one of attention, not correctness — a real spec has dozens of operations and hundreds of lines, and a parameter that silently became required reads exactly like the harmless reorder three lines above it.
This tool reads only the parts of the contract that can break a client — operations, parameters, and request-body requiredness — and sorts every difference into breaking or non-breaking before you look at a single line. It says nothing about a reworded description or a reordered tag list, because neither can break anything.
| Question | Where to answer it |
|---|---|
| Did a required parameter get added, or an optional one become required? | This tool's breaking list, immediately. |
| Was any endpoint removed? | This tool's breaking list. |
| Did a description or example change? | Neither tool flags this as breaking — read the raw diff if you need to review wording changes. |
| Did a field deep inside a request body's JSON Schema change? | Neither tool catches this today — this tool's structural comparison stops at a request body's own required flag; a full schema-aware diff tool would be needed for schema-level coverage. |
| Is anything I paste uploaded anywhere? | No, for this tool — everything runs in your browser. Pasting a spec into an online diff tool may log or cache it; check its own policy first if your spec is not public. |
Every difference between the two documents, with equal visual weight: a reordered object key, a reworded description, a new example value, and a parameter that just became required all look the same in a text diff. On a spec with dozens of operations, the one change that would actually break a client is easy to scroll past.
Yes, when you need to review everything that changed, not just what would break a client — a new example, an updated description, a reordered tag list, or a change deep inside a request or response body's JSON Schema that this tool's shallow structural comparison does not look at. A full-document diff or an OpenAPI-aware structural diff tool with schema-level coverage is the right choice for that review.
You can, and for a small change that is often faster. The risk is the same as any manual review: the author already believes the change is safe, which is exactly the blind spot a mechanical, exhaustive comparison exists to catch, and it costs nothing to run alongside a human review rather than instead of one.
No. Neither a raw diff nor this tool's structural comparison understands your clients' actual behavior — a client that never sends the removed parameter is unaffected by its removal, and this tool has no way to know that. Both only tell you what the contract itself declares differently; deciding whether that is safe to ship is a judgment call the two documents alone cannot make for you.