Catch API Changes with Structural JSON Diff

Separate formatting from contract change

Plain-text diff becomes noisy when indentation, key order, or line endings change. Structural diff parses JSON and compares paths such as /customer/address/city, separating presentation from meaningful data changes.

Adding a key is often backward-compatible; removing a required field or changing string to number may break consumers. The tool identifies change, while the consumer contract determines impact.

Choose array semantics explicitly

Index comparison fits ordered events and tuple-like arrays. In object lists with stable IDs, inserting one item at the front can make every later index appear changed. Match by a stable key or sort only when order is not meaningful.

Automatic sorting can hide a real ordering regression. State whether an array is a set or a sequence in the test contract.

• Document identity fields.
• State order semantics in tests.
• Bound node count and depth for large payloads.

Prioritize type changes

The difference among null, boolean, number, string, array, and object directly affects consumers. `true` and `"true"` look close but behave differently in conditions, serialization, and schema validation.

Check numeric precision and date formats separately. JSON numbers can exceed JavaScript safe integers; dates are strings until a schema or domain rule validates them.

Complete diff with schema and consumer tests

Structural equality is not JSON Schema validation. Use schemas for required fields, patterns, enums, and additional-property rules, then combine diff reports with OpenAPI contract tests and consumer fixtures.

Do not persist sensitive production payloads in CI. Use representative anonymized fixtures and check reports for tokens or identifiers. In-browser review reduces transfer, but users control copied output afterward.