How to compare two JSON files

Why a text diff misleads

JSON does not define object key order, so two serialisers can emit the same data in different orders and a text diff will call every line changed. The same happens with indentation changes, line-ending changes, and whether the file was minified.

None of those are differences in the data. A text diff on JSON has a high false-positive rate, and the real change hides inside the noise.

What a structural diff does

It parses both sides and walks the values, reporting three kinds of result: a path present only on the left (removed), a path present only on the right (added), and a path present on both with different values (changed). Key order and formatting are ignored because they carry no meaning.

- $.user.legacyId          42
+ $.user.uuid              "8f2c…"
~ $.order.total            19.99 → 24.99
~ $.order.paid             false → true   (boolean → boolean)

Array order is a real choice

Unlike object keys, array order is meaningful in JSON — so by default it should be compared. But a list of tags or permissions returned in a different order by two servers is usually not a change.

Compare arrays as ordered sequences by default, and switch to treating them as unordered sets only when you know the order carries no meaning. Switching it off globally will hide genuine reordering bugs.

Numbers that are equal but not identical

1.0 and 1 are the same number and different text. 0.1 + 0.2 serialised is 0.30000000000000004. Two systems can compute the same value and print it differently.

A structural diff compares parsed values, which handles 1.0 versus 1. It cannot decide for you whether a floating-point difference in the fifteenth decimal place matters — if it does not, round both sides before comparing.

A practical routine

• Format both documents with the same indentation.
• Sort keys on both, so any text diff you also run is meaningful.
• Run the structural diff and read added/removed/changed separately — they usually have different causes.
• For an API regression, diff a captured response against a known-good one rather than against the documentation.