JSON compare and diff

A text diff treats JSON as lines, so it reports differences that are not real and buries the ones that are. Reorder the keys of an object and every line looks changed, although the data is identical. Reformat one side and the diff fills with whitespace. A structural comparison parses both documents and compares values, so {"a":1,"b":2} and {"b":2,"a":1} are equal, 1 and 1.0 are the same number, and indentation never matters.

Each difference then comes with its path, such as $.items[1].price, which is what you need to write an assertion, file a defect or explain a failing test. A text diff gives you a line number in one particular formatting of the document.

Changed means the field exists on both sides with a different value. Added means it exists only in the actual JSON, and removed means it exists only in the expected JSON. Type changed means the field exists on both sides but holds a different type, such as the string "59.90" where the number 59.9 was expected.

Type changes deserve attention in API testing. A price that becomes a string, a null where an object used to be, or a single item that is no longer wrapped in an array often passes a loose check and then breaks a client that parses the response strictly.

Arrays are where most JSON diff tools mislead. Comparing item by item means one item inserted at the start reports every item after it as changed. This tool aligns the two arrays first, the way a good text diff aligns lines, so an insertion is one addition and an edit is one change, even when they sit next to each other.

When order carries no meaning, choose Ignore order: the same items in any order are equal, and duplicates are still counted. When items have an identifier, choose Match by key and enter the field, such as id or sku. Each item is then compared with its own counterpart wherever it moved, which is how most API test assertions should treat lists of records.

Responses captured at different times always differ in timestamps, request IDs, ETags and generated identifiers. Unless those are excluded, the comparison never comes back clean and the real differences are easy to miss. A bare name, such as updatedAt, skips that key wherever it appears. A path, such as $.meta.requestId or $.items[*].id, skips one place, with * standing for any key and [*] for any array item.

Keep the ignore list short and specific. Every field you ignore is a field your test no longer checks, so ignore what is generated, not what is inconvenient. The number of ignored fields is shown with the result so that it stays visible.

For a regression check, compare a response from the previous release with one from the release candidate. For a contract change, compare the documented example with what the service now returns. For a data migration, compare an export from the old system with one from the new.

The exports fit those workflows. The paths list drops straight into the ignore option of most assertion libraries. The Markdown table goes into a defect report. JSON Patch, the RFC 6902 format, describes the exact operations that turn the expected document into the actual one, which suits test fixtures and review.