- Home
- Skills
- APIs & Backend
- OpenAPI Breaking Changes: Diff two specs before release
More screenshots
Works with the AI Agents you already use
OpenAPI Breaking Changes: Diff two specs before release
Don't learn about a breaking change from your API consumers. Diff two OpenAPI 3 JSON specs and list every break: removed endpoints, new required fields, narrowed enums and changed responses.
$15
OpenAPI Breaking Changes: Diff two specs before release
Example session with this skill installed
Compare references/baseline.json with references/breaking.json, produce Markdown, and explain the highest-priority consumer fixes without waiving rules.
- Read your context and instructions
- Compiled the openapi breaking changes
OpenAPI compatibility report
11 breaking; 2 non-breaking; 11 gated.
- BREAKING: GET /items | query/filter | parameter_removed | removed or renamed parameter
- BREAKING: GET /items | query/region | parameter_added | new parameter
- NON-BREAKING: GET /items | query/search | parameter_added | new parameter
- BREAKING: GET /items | responses/404 | status_removed | response status removed
- BREAKING: GET /items | responses/200/application/json.id | property_removed | response property removed
- BREAKING: GET /items | responses/200/application/json.state | enum_changed | enum ['open'] -> ['open', 'archived'] (response)
- BREAKING: GET /items | security | auth_changed | security alternatives/scopes changed
- BREAKING: POST /items | query/filter | parameter_removed | removed or renamed parameter
- BREAKING: POST /items | query/region | parameter_added | new parameter
- NON-BREAKING: POST /items | query/search | parameter_added | new parameter
- BREAKING: POST /items | requestBody/application/json.name | required_property_added | request property now required
- BREAKING: POST /items | requestBody/application/json.name | nullable_changed | nullable True -> False (request)
- BREAKING: * /legacy | /legacy | path_removed | path and its operations removed
Supported structural rules only; see references/rules.md for unchecked behavior.
Release gated (exit 1): 11 breaking, 2 non-breaking, 0 waived. Restore the old filter and legacy route, avoid a newly mandatory region, and preserve response id/404 guarantees. Then coordinate authentication, archived response states, and required non-null request name with consumers. If these changes are intentional, publish them as a parallel version. Bumping the version number alone doesn't protect existing callers.
Connects securely to your tools. The creator never sees your data.
About this skill
The problem You changed an OpenAPI spec and want to ship it as a patch. A renamed query parameter or a field that's now required looks harmless in the diff, but every client still sending the old request will break. You want to know that before you pick a version number, not after a consumer files a bug.
See it before you buy: real input, real output Command (from the package folder, exit code 1, 0.023 s):
python3 -I -B scripts/openapi_diff.py references/baseline.json references/breaking.json --format markdown
Before: Two versions of the same API contract: baseline.json and breaking.json (OpenAPI 3.1, JSON).
After: lines copied from the script's output (excerpt):
11 breaking; 2 non-breaking; 11 gated.
- BREAKING: GET /items | query/filter | parameter_removed | removed or renamed parameter
- BREAKING: GET /items | responses/404 | status_removed | response status removed
- BREAKING: POST /items | query/filter | parameter_removed | removed or renamed parameter
- BREAKING: * /legacy | /legacy | path_removed | path and its operations removed
What the numbers show
- Ran on two real releases of the public Swagger Petstore spec (1.0.3 and 1.0.29, 19 operations each): 8 breaking and 32 non-breaking changes.
- I checked all 8 breaks and 2 of the additions by hand against both spec versions: all 10 were real.
- Honest limit: this shows the reported findings are right, not how many changes it misses. The Petstore run printed 5 warnings about things it doesn't compare.
What you get
- A Python script that compares the released spec with your new one. It has 19 rules covering paths, operations, parameters, request and response fields, media types, status codes and auth requirements.
- Instructions that tell the agent to run it, explain what each break means for callers, and list fixes in priority order.
- A JSON report for CI and a Markdown report for pull request review. Both list each finding with its endpoint and location.
- Exit codes you can gate on: 0 means no unaccepted breaks, 1 means at least one break is blocking, 2 means the input couldn't be read.
--allow-breaking-forto accept a whole rule (say, removed status codes) when you mean it. Accepted breaks still show in the report.- Example specs, rule notes, 26 test cases and 4 saved sample reports you can check against a fresh run.
Measured on real data (full detail) I ran it on two real releases of the public Swagger Petstore spec, 1.0.3 and 1.0.29. Each has 13 paths and 19 operations. The originals are YAML, so I converted them to JSON and inlined their internal references first. The script only reads JSON.
| Comparison | Breaking | Non-breaking | Blocking the release | Typical run time |
|---|---|---|---|---|
| Petstore 1.0.3 → 1.0.29 | 8 | 32 | 8 | 0.03 s |
| Included breaking example | 11 | 2 | 11 | 0.03 s |
| Included compatible example | 0 | 3 | 0 | 0.03 s |
I checked all 8 Petstore breaks and 2 of the additions by hand against both spec versions. All 10 were real and matched the documented rule. That tells you the reported findings are right. It doesn't tell you how many changes the script misses. The Petstore run also printed 5 warnings about things it doesn't compare, like formats and additionalProperties, so you'd review those yourself. Run time is the median of 5 runs including Python startup, on an ordinary Linux machine. The conversion steps, file hashes and exact commands are in references/benchmarks.md.
Known limitations
- Accepts OpenAPI 3.0/3.1 JSON only. Convert YAML separately with a trusted tool.
- Rejects external references, cycles, and assertion siblings beside references, even in unused components.
- Doesn't fully compare composition, constraints, headers, serialization, or runtime behavior. Review warnings and run consumer tests.
- Treats type changes as breaking. Added response statuses and media types are non-breaking by policy, which may not suit clients that reject unexpected values.
- Waivers apply to a whole rule across the comparison. Exit 0 doesn't prove consumer compatibility.
Who it's for API maintainers reviewing pull requests and release owners who need to explain contract changes to consumers.
Requires Python 3.8+, two UTF-8 OpenAPI 3.0.x/3.1.x JSON files, and an agent host that can read text and run Python. The script uses the standard library and needs no installed packages. The benchmark's YAML converter isn't included or needed for JSON inputs.
Privacy: runs locally, no network, no telemetry, and writes nothing unless you redirect output.
Check it yourself
26 test cases and 4 saved sample outputs were checked against fresh runs. From the package folder, run python3 -I -B scripts/openapi_diff.py references/baseline.json references/breaking.json --format markdown to reproduce the demo, which exits 1 with 11 breaking findings. Use references/compatible.json as the candidate for exit 0 with 3 non-breaking changes. See references/benchmarks.md to rerun all cases and reproduce the prepared public comparison.
Price and guarantee $15 one time, yours to use with any agent that can run Python. Covered by Agensi's money-back guarantee if it doesn't do what this page promises.
No YAML or OpenAPI 2.0 support. Ignores webhooks, headers, and validation constraints. Requires Python 3.8+. Limited to 100,000 nodes or 100 reference hops.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 15 days ago
Requires
Permissions
Uses the host's terminal to invoke Python and file-read access for the two user-supplied specifications. The script reads only those inputs, prints stdout/stderr, and writes no files. Optional shell redirection saves output at the user's chosen path. No network access, no telemetry, and nothing is sent anywhere.