# API Breaking Change Check for OpenAPI API Breaking Change Check for OpenAPI is a tested SKILL.md that compares two versions of one API description (OpenAPI 3.0 or 3.1 in YAML or JSON, or two JSON Schemas of one request or response) and lists ONLY the changes that break clients written against the old version, one line each with a fixed code, the place, old and new, and who breaks - or exactly No breaking changes; an agent buys it once for $0.03 over x402. - Page: https://aiskills402.com/skills/api-breaking-change-check - Category: Code & Engineering (https://aiskills402.com/categories/code) - Price: $0.03 once, USD-priced, paid in USDC on Base over x402. Price as loaded on this page. The 402 response your agent receives is authoritative. - Version: 1.0.1 - Card (JSON): https://api.aiskills402.com/v1/skills/api-breaking-change-check ## Use it when Compares two versions of one API description (OpenAPI 3.0 or 3.1 in YAML or JSON, or two JSON Schemas of one request or response) and lists ONLY the changes that break clients written against the old version, one line each with a fixed code, the place, old and new, and who breaks - or exactly No breaking changes. The skill judges by direction - a request may widen safely and breaks when it narrows, a response may narrow safely and breaks when it widens - and it follows each $ref and allOf to the operations that use it, so a change made only in a shared schema is still found, while a renamed path variable, a new optional field, a reformatted file and a field moved between allOf branches are left out. Use to check an API change before release, review a pull request that edits an OpenAPI file, or gate a pipeline on breaking changes. ## Not for Writing an OpenAPI operation from an example call, listing every difference between two JSON documents, or judging server behaviour the description does not show. It reads two pasted versions of one API description, treats a newly documented error response as not breaking, and gives no versioning advice. ## Tested, honestly Tested 2026-10-18. - Strong model (claude-sonnet-5-5 (Claude Code alias "sonnet")): Right on all 33 pairs of API descriptions, read by hand: it listed removed endpoints, new required fields and parameters, narrowed limits, removed response fields, a response field that may now be absent, null newly allowed in a response in both the 3.0 and the 3.1 spelling, a replaced success status, auth added on one operation or on the whole API, type changes, a new response enum value and a changed default of an optional query parameter. It left out the safe look-alikes that sat beside each break (a renamed path variable, a field moved between allOf branches, null newly allowed in a request, a deprecated flag) and answered exactly No breaking changes. on all seven controls, including the one where a response enum lost a value. - Weak model (claude-haiku-5-5 (Claude Code alias "haiku")): Right on all 33 pairs with the skill, read by hand: every planted break came out as one coded line with the place, old and new, and which clients are hit, the safe look-alikes stayed out, a removed response enum value was judged safe, a changed default of an optional parameter was listed, and each of the seven controls got exactly No breaking changes. Note: Thirty-three pairs of an OpenAPI description written by us from one bookshop description (OpenAPI 3.0 and 3.1, YAML and JSON): 26 with a planted breaking change, each carrying a safe look-alike change as bait, and 7 controls with only safe changes. Sixteen of the pairs are the real starting point, two documents and no release note pointing at the change. With the skill each answer is scored by code: the exact set of finding codes, the place named, one line per change, the fixed sentence for a control, no fence. Without the skill the same request is scored on the same points by content checks in any wording, with a fence removed first. After reading every difference by hand the content checks were widened for both sides: (1) a reported break also counts when it says clients get a value "without it/them", "absent" or "omit..."; (2) it also counts with "refus..."; (3) the nothing-breaks check for controls also accepts "Nothing in AFTER breaks..." and "No changes break existing clients."; (4) a line starting "Nothing breaks." is no longer read as calling a safe change breaking. Each widening was proven able to fail: removing it turned the control script red. Before the widening the counts were Sonnet 32 against 28 and Haiku 33 against 27; after reading by hand the gain shrank to 2 for each. All facts come from the public OpenAPI 3.0.3 and 3.1.0 and JSON Schema 2020-12 texts, read on 18 October 2026; there are no owner-measured facts. One run per model and case. ### With and without the skill Tested 2026-10-18. - Pairs judged right (33 pairs): Sonnet 33/33 with, 31/33 without; Haiku 33/33 with, 31/33 without. Same request on both sides. Read by hand, both bare models already handled removed endpoints, new required fields, narrowed limits, removed response fields, nullable in 3.0 and 3.1, status changes, added auth and type changes, and ignored a renamed path variable, an allOf refactor, null newly allowed in a request and a deprecated flag. Two situations differ. A default of the optional limit parameter moved from 20 to 50: Sonnet saw it and left it out on purpose as a behaviour shift, Haiku did not mention it. The value shipped was removed from a response enum: both called it breaking; the skill says safe, since the response stays inside the old values. That is the skill's policy, not the OpenAPI standard, and a reader could side with the bare model. Same cases and the same checks with and without the skill. The cases are ours, written around what the skill is for; with a handful of cases, a difference of one or two is within noise. Full summary: https://aiskills402.com/skills/api-breaking-change-check/tests ## Example ### English (claude-sonnet-5-5) Before: > === BEFORE (bookshop-api-2.3.0.yaml) === openapi: 3.1.0 info: title: Bookshop API version: 2.3.0 servers: - url: https://api.example.com paths: /books: get: summary: List books parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sort… After: > ENDPOINT-REMOVED — DELETE /books/{id} — operation present → removed — clients that delete a book get an error (405 or 404) instead of 204 ## What is in the file - The answer - The direction rule - How to read the two texts - The codes - Rules - Work in this order - Short example ## Languages English ## How to buy Agent (HTTP): 1. GET https://api.aiskills402.com/v1/skills/api-breaking-change-check/file without a payment header. The answer is 402 with a PAYMENT-REQUIRED header (x402 v2): exact amount, asset, network, recipient. 2. Sign `accepts[0]` with an x402 client (for example @x402/core + @x402/evm). 3. Repeat the GET with the signature in the PAYMENT-SIGNATURE header. The answer is 200 with the file, its sha256 and a re-download token. Agent (MCP): https://mcp.aiskills402.com/mcp — free tools search_skills, get_skill, redownload_skill. Buying itself is over HTTP. Full flow: https://aiskills402.com/docs ## The file - Version: 1.0.1 - Size: 10.7 KB (10907 bytes) - SHA-256: 77ceb26bea46569473e9985e740bf927758475e9cfdfbf7cafdd05fd86fbddee - Updated: 2026-10-18 - New versions are free through your re-download token. ## Versions ### 1.0.1 (2026-10-18) Changelog only, the skill file is unchanged: one line of this changelog repeated a rule sentence of the paid file word for word (found by the public-page leak check after 1.0.0) and is reworded; the "problems when removed" counts of the four widened checks were matched to the wrong lines and are corrected; the first widening now has its own line in control.mjs. ### 1.0.0 (2026-10-18) First release: compares two versions of one API description (OpenAPI 3.0 or 3.1 in YAML or JSON, or two JSON Schemas of one request or response) and lists only the changes that break clients written against the old version, one line each `CODE — where — old → new — who breaks`, or exactly `No breaking changes.` Ten codes: ENDPOINT-REMOVED, REQUIRED-ADDED, REQUEST-NARROWED, RESPONSE-FIELD-REMOVED, RESPONSE-WIDENED, RESPONSE-ENUM-ADDED, STATUS-CHANGED, DEFAULT-CHANGED, AUTH-ADDED, TYPE-CHANGED. The core rule is direction: a request may widen and breaks when it narrows; a response may narrow and breaks when it widens. Facts: public standards only (OpenAPI 3.0.3 and 3.1.0, JSON Schema 2020-12 validation), read on 18 October 2026 with curl; the three standard addresses and our own published description answered 200. No owner measurements, no dated line in SKILL.md, no paid or model call for the writing. Decisions (one line each): - A response enum that gains a value is reported as RESPONSE-ENUM-ADDED, with the reason "breaks strict clients"; the shared request says a client handles only what the old version says it can receive. - A newly documented error response is NOT reported (it says what the server may send, not that it started to; tools disagree). The brief listed "new status code" as breaking; narrowed to a replaced or removed success status because the wider rule has no clean test. - The optional "N non-breaking changes not listed" summary line of the brief was dropped: controls must be exactly one sentence, and a planted answer must have only finding lines (a test checks that every non-empty line starts with a code). - Renaming a path variable alone is not breaking; a path whose segments changed is ENDPOINT-REMOVED. - A type change is judged by values: integer to number is safe in a request and breaks in a response; adding or removing null is judged by direction and is never TYPE-CHANGED. - A schema used in both directions is judged in each direction and may give two lines; the same change reached through several operations by one shared schema is one line that names them. - A top-level security requirement counts as AUTH-ADDED for operations that have none of their own (the spec says an operation's own definition overrides the top-level one). - A deprecated flag, a version number, descriptions, examples, tags, operation ids and key order are never breaking. - Notes from the authors of the change are claims; two cases carry a note that asks the reviewer to answer that nothing breaks. Test (written, not yet run): 33 cases built by `test/make-cases.mjs` from one base spec (a bookshop on api.example.com, OpenAPI 3.0.3 and 3.1.0, YAML and JSON, ten finding codes) by scripted mutations, so each expected answer is known by construction — 26 planted (3 hard), 7 controls, 16 from the real starting point (two documents and nothing else; the other half carry a short, vague note from the authors). Every planted case also carries at least one safe decoy (optional request field, renamed path variable, new optional query parameter, new endpoint, new response field, widened request enum, relaxed limits, removed response enum value, nullable on a request field, deprecated flag, a field moved between allOf branches), so listing every difference fails. `test/control.mjs` checks every planted case against realistic wrong answers on both sides (a safe change called breaking, a missed finding, a neighbouring code, a surplus code, a wrong place, the fixed sentence for a defect, a fence, extra text), every control against any deviation from the sentence, and every ideal answer; `test/no-leak.mjs` checks that no test answer, test-only name or 6-word run is in SKILL.md. ## License Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing. Holder: Georgi Kalchev, aiskills402.com. Terms: https://aiskills402.com/docs#license ## FAQ ### Path variable renamed in a new release: reported? The URL a client calls is the same. The OpenAPI specification itself treats two templates that differ only in a variable name as identical, so the skill leaves a rename of the variable, in the template and in its parameter entry, out of the list. A path whose shape changed is reported, because the old URL no longer exists for the clients that still call it. ### What is the direction rule? Ask which way the data flows. A request may widen and breaks when it narrows: a new required field, a removed enum value or a tighter limit fail old clients, while a new optional field passes. A response may narrow and breaks when it widens: a removed field, a value that may now be null, or a new enum value fail clients that read the old description as a closed contract. ### Does it find a change that exists only in a shared schema? Yes. It follows each reference to the operations that use the schema and reports the change in the direction of that use, so a field newly required inside a nested address object is found even though the line that refers to it was never touched. It also reads the OpenAPI 3.0 nullable flag and the 3.1 type list as one and the same change, and ignores a field that merely moved between allOf branches. ### Does it help Claude Sonnet? Slightly. The 33 test pairs were one bookshop API description edited 33 ways: 26 with a real break next to a harmless look-alike, 7 where nothing breaks. Sonnet knew nearly every rule already, from removed endpoints to nullable in both spellings. It erred on two: a changed default of an optional page-size parameter, and a value dropped from a response enum, which it called breaking while the skill's own policy says safe. With the skill loaded, Sonnet rose from 31 right to all 33, and Haiku made the same climb. ## Related skills - [OpenAPI Operation Object From An Example Call](https://aiskills402.com/skills/openapi-operation-from-example.md): $0.01 once - [JSON Diff Paths](https://aiskills402.com/skills/json-diff-paths.md): $0.01 once ## Measurement limits - Models other than the two named above were not run. - Each verdict comes from the test run on the date shown; the skill may have changed since (check the version). - Full test inputs are not published here, only short excerpts of our own text. - Results on your own texts, languages and domains can differ. Offer note: Paid in USDC (USD-pegged) over x402 by an AI agent; one-time.