Response Contract Comparator

Runs in browser Validation

Detect removed fields, type changes, new required properties and nullable changes between an expected response shape and a real response, classifying each as breaking, risky or safe.

Privacy: This tool runs entirely in your browser. Your input never leaves your device.

How to use Response Contract Comparator

  1. Paste the expected contract: a known-good example response or a JSON Schema (JSON or YAML).
  2. Paste the actual response (or the new schema) on the right.
  3. Leave the mode on auto-detect, or force example/schema mode.
  4. Read the verdict and the table sorted by severity; breaking rows need a version bump or a fix.

Response Contract Comparator features

  • Three modes: example vs response, JSON Schema vs response, and schema vs schema
  • Breaking: removed fields, type changes, value → null, new required properties, removed enum values, required → optional
  • Risky: enum growth, format/pattern changes, integer → number, tightened constraints, new oneOf/anyOf alternatives
  • Safe: added optional fields and relaxed constraints
  • Array items compared against the expected item shape with repeated differences collapsed
  • Verdict with counts and a downloadable differences table (path, change, expected, actual)

Response Contract Comparator example

Order response after a backend change

Input:

Expected: { "id": 1042, "customer": { "email": "layla@example.com" }, "total": 39.98, "createdAt": "2026-09-01T10:00:00Z" }
Actual:   { "id": "1042", "customer": { "tier": "gold" }, "total": null, "createdAt": "01/09/2026" }

Output:

Verdict: Breaking — 3 breaking changes and 1 risky.
breaking · $.id · type-change: Type changed from integer to string.
breaking · $.customer.email · removed-field: Field "email" is missing from the response.
breaking · $.total · value-to-null: Expected a number but the response returned null.
risky · $.createdAt · format-change: Expected a date-time formatted string but got a plain string.
safe · $.customer.tier · added-field: New field "tier" was added.

Frequently asked questions about Response Contract Comparator

What counts as breaking?

Removed fields, type changes, a value that became null, new required properties, enum values removed and fields that are no longer guaranteed (required → optional).

What is risky?

Changes that strict consumers may reject: new enum values, format or pattern changes, integer relaxed to number, tightened constraints or new oneOf/anyOf alternatives.

What is safe?

Added optional fields and relaxed constraints — consumers that ignore unknown fields keep working.

Can I compare two schemas?

Yes. Paste the old JSON Schema as expected and the new one as actual; the tool detects schema-vs-schema mode automatically or via the mode selector.

How are arrays compared in example mode?

Every item in the actual array (up to 25) is compared against the first item of the expected array, and repeated differences are collapsed into one row.

Technical notes

Example mode infers a type for every value (null, boolean, integer, number, string, array, object) and a format for strings (date-time, date, uuid, email, url) so that a date that changes shape is reported as risky rather than silently accepted. Each actual array item is compared against the first expected item, and identical differences across items are reported once with an [] path.

Schema mode reuses the JSON Schema validator and maps keyword violations to severities: required → breaking, type → breaking, additionalProperties → safe (added field), enum/format/pattern/constraints → risky. Schema-vs-schema mode walks both schemas in parallel, including nullable, enum, format, constraints, required lists, additionalProperties, items and composition keywords.