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.

What is API contract testing?

An API contract is the agreed description of an interface — its endpoints, parameters, request and response schemas and status codes — usually written as an OpenAPI document. Contract testing compares what a service actually returns with that description, so a renamed field or a changed type is caught by the producer or the consumer before it breaks the other side.

Read the guide: What is API Testing? How to Test a REST API

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.
  5. If fields such as request ids or timestamps change on every call and are not part of the contract, list them under "Ignore these paths" (or tick the volatile-field option).

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)
  • Optional exclusions: paths to ignore ($.a.b, [*], *, ** or a bare key) and a volatile-field switch for ids, timestamps, tokens and cursors — ignored differences are listed, not hidden

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.

Can I exclude fields that change on every response?

Yes. List paths to ignore, one per line — $.meta.requestId, $.items[*].etag, **.debug, or a bare key such as updatedAt that matches anywhere — or tick "Also ignore volatile fields" for ids, timestamps, tokens, cursors and versions. The verdict is computed without them, and every ignored difference is still listed in the notes, with a warning when one of them would have been breaking.

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.

References

  • OpenAPI SpecificationOpenAPI InitiativeThe standard for describing REST APIs: paths, operations, parameters, schemas, responses and security schemes.
  • JSON Schema SpecificationJSON SchemaThe vocabulary for describing and validating the shape of JSON documents (types, required properties, formats).
  • RFC 9110: HTTP SemanticsIETF · 2022The meaning of HTTP methods, header fields, status codes and content negotiation, independent of the wire version.