{"id":"schema-compat","title":"Breaking-change diff between two JSON Schemas or OpenAPI documents, and whether cached calls still validate","description":"Compares an old and a new JSON Schema 2020-12 (or two OpenAPI 3.0/3.1 documents) and lists each change with its path, keyword, old and new value, whether it narrows or widens what is accepted, and whether it breaks clients: newly required properties, removed or retyped properties, removed enum values, tightened limits, additionalProperties flips, removed operations, removed or newly required parameters, removed media types and responses. Role request (default) treats narrowing as breaking; role response treats widening and removed required fields as breaking. You may also pass cached tool-call arguments: each is validated against the old and the new schema, so a call that worked before and fails now is reported with the failing JSON pointer. Changes it cannot prove either way (pattern rewrites, not/if/then, mixed oneOf edits) are reported as uncomparable and the status is unsupported rather than pass.","roi":"Catches the schema change that silently breaks every cached agent call. 400 operations and 50 cached calls per $0.005 call.","audience":"developer","package":"data-contract-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/schema-compat","path":"/api/v1/schema-compat","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["before","after","kind"],"properties":{"before":{"description":"The old schema, or old OpenAPI document. Full JSON Schema 2020-12 (local $ref only)."},"after":{"description":"The new schema, or new OpenAPI document. Full JSON Schema 2020-12 (local $ref only)."},"kind":{"type":"string","enum":["json-schema","openapi"]},"role":{"type":"string","enum":["request","response"],"description":"json-schema only: request (default) or response; OpenAPI compares each side in its own role."},"calls":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["arguments"],"properties":{"name":{"type":"string","maxLength":80},"arguments":{"description":"Cached call arguments (JSON schema: validated against the root; OpenAPI: against the operation's JSON request body)."},"operation":{"type":"object","additionalProperties":false,"required":["path","method"],"properties":{"path":{"type":"string","maxLength":500},"method":{"type":"string","enum":["get","put","post","delete","options","head","patch","trace"]}}}}}}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"changes":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string","description":"OpenAPI only: METHOD /path."},"path":{"type":"string","description":"JSON pointer into the schema (json-schema) or into the operation (openapi)."},"keyword":{"type":"string"},"effect":{"type":"string","enum":["narrows","widens","changed","uncomparable","neutral"]},"breaking":{"type":"boolean"},"before":{"description":"Old value."},"after":{"description":"New value."},"detail":{"type":"string"}}}},"counts":{"type":"object","properties":{"breaking":{"type":"integer"},"uncomparable":{"type":"integer"},"nonBreaking":{"type":"integer"},"operationsCompared":{"type":"integer"}}},"calls":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string"},"before":{"type":"string","enum":["valid","invalid","unknown"]},"after":{"type":"string","enum":["valid","invalid","unknown"]},"regression":{"type":"boolean","description":"Valid before, invalid after."},"errors":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"keyword":{"type":"string"},"message":{"type":"string"}}}}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"changes":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string","description":"OpenAPI only: METHOD /path."},"path":{"type":"string","description":"JSON pointer into the schema (json-schema) or into the operation (openapi)."},"keyword":{"type":"string"},"effect":{"type":"string","enum":["narrows","widens","changed","uncomparable","neutral"]},"breaking":{"type":"boolean"},"before":{"description":"Old value."},"after":{"description":"New value."},"detail":{"type":"string"}}}},"counts":{"type":"object","properties":{"breaking":{"type":"integer"},"uncomparable":{"type":"integer"},"nonBreaking":{"type":"integer"},"operationsCompared":{"type":"integer"}}},"calls":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string"},"before":{"type":"string","enum":["valid","invalid","unknown"]},"after":{"type":"string","enum":["valid","invalid","unknown"]},"regression":{"type":"boolean","description":"Valid before, invalid after."},"errors":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"keyword":{"type":"string"},"message":{"type":"string"}}}}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"kind":"json-schema","before":{"type":"object","required":["id"],"properties":{"id":{"type":"integer"},"mode":{"enum":["fast","slow"]},"note":{"type":"string"}}},"after":{"type":"object","required":["id","region"],"properties":{"id":{"type":"integer"},"mode":{"enum":["fast"]},"note":{"type":"string","maxLength":10},"region":{"type":"string"}}},"calls":[{"name":"cached","arguments":{"id":1,"mode":"slow"}}]},"openapiOperation":{"operationId":"schema_compat","summary":"Breaking-change diff between two JSON Schemas or OpenAPI documents, and whether cached calls still validate","description":"Compares an old and a new JSON Schema 2020-12 (or two OpenAPI 3.0/3.1 documents) and lists each change with its path, keyword, old and new value, whether it narrows or widens what is accepted, and whether it breaks clients: newly required properties, removed or retyped properties, removed enum values, tightened limits, additionalProperties flips, removed operations, removed or newly required parameters, removed media types and responses. Role request (default) treats narrowing as breaking; role response treats widening and removed required fields as breaking. You may also pass cached tool-call arguments: each is validated against the old and the new schema, so a call that worked before and fails now is reported with the failing JSON pointer. Changes it cannot prove either way (pattern rewrites, not/if/then, mixed oneOf edits) are reported as uncomparable and the status is unsupported rather than pass.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"developer","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/schema-compat","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["before","after","kind"],"properties":{"before":{"description":"The old schema, or old OpenAPI document. Full JSON Schema 2020-12 (local $ref only)."},"after":{"description":"The new schema, or new OpenAPI document. Full JSON Schema 2020-12 (local $ref only)."},"kind":{"type":"string","enum":["json-schema","openapi"]},"role":{"type":"string","enum":["request","response"],"description":"json-schema only: request (default) or response; OpenAPI compares each side in its own role."},"calls":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["arguments"],"properties":{"name":{"type":"string","maxLength":80},"arguments":{"description":"Cached call arguments (JSON schema: validated against the root; OpenAPI: against the operation's JSON request body)."},"operation":{"type":"object","additionalProperties":false,"required":["path","method"],"properties":{"path":{"type":"string","maxLength":500},"method":{"type":"string","enum":["get","put","post","delete","options","head","patch","trace"]}}}}}}}},"example":{"kind":"json-schema","before":{"type":"object","required":["id"],"properties":{"id":{"type":"integer"},"mode":{"enum":["fast","slow"]},"note":{"type":"string"}}},"after":{"type":"object","required":["id","region"],"properties":{"id":{"type":"integer"},"mode":{"enum":["fast"]},"note":{"type":"string","maxLength":10},"region":{"type":"string"}}},"calls":[{"name":"cached","arguments":{"id":1,"mode":"slow"}}]}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"changes":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string","description":"OpenAPI only: METHOD /path."},"path":{"type":"string","description":"JSON pointer into the schema (json-schema) or into the operation (openapi)."},"keyword":{"type":"string"},"effect":{"type":"string","enum":["narrows","widens","changed","uncomparable","neutral"]},"breaking":{"type":"boolean"},"before":{"description":"Old value."},"after":{"description":"New value."},"detail":{"type":"string"}}}},"counts":{"type":"object","properties":{"breaking":{"type":"integer"},"uncomparable":{"type":"integer"},"nonBreaking":{"type":"integer"},"operationsCompared":{"type":"integer"}}},"calls":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string"},"before":{"type":"string","enum":["valid","invalid","unknown"]},"after":{"type":"string","enum":["valid","invalid","unknown"]},"regression":{"type":"boolean","description":"Valid before, invalid after."},"errors":{"type":"array","items":{"type":"object","properties":{"instancePath":{"type":"string"},"keyword":{"type":"string"},"message":{"type":"string"}}}}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/schema-compat/","docsJson":"https://agents.writerslogic.com/docs/schema-compat.json","sample":"https://agents.writerslogic.com/api/v1/samples/schema-compat","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}