· 6 min read
Running a normal text diff over two JSON files usually produces a wall of changes that mean nothing. Keys came back in a different order, one file is pretty-printed and the other is not, and a float is written slightly differently. None of that is a real difference, and it buries the one change you were looking for.
A text diff compares lines. JSON does not care about lines. Object keys have no defined order, whitespace is insignificant, and the same number can be written more than one way. Two documents that are semantically identical can differ on every line, and two documents that differ in one important value can look almost the same.
A structural comparison parses both sides first and then walks the trees together. It reports differences by path rather than by line, so you get something like a key that exists only on the right, or a value that changed at a specific location, rather than a block of red and green.
Arrays are the genuinely hard part, and it is worth knowing what your tool assumes. Comparing by position says that inserting one element at the start changed every element. Comparing as a set says two arrays with the same items in a different order are identical, which is wrong when the order is meaningful, such as a list of steps.
There is no universally correct answer. Position-based comparison is the safe default because it never claims two different documents are the same, at the cost of being noisy when a list has been reordered.
| Difference | Usually matters? |
|---|---|
| A key present on one side only | Yes, almost always |
| A value changed at the same path | Yes |
| Key order changed | No |
| Indentation or line endings changed | No |
| A number written as 1.0 instead of 1 | Rarely, but check the consumer |
| An array reordered | Depends entirely on what the array represents |
Validate both files first, because a structural comparison cannot start until both parse, and a failure at this stage is usually the real answer. Then compare, and read added and removed entries before changed ones: a missing key explains more downstream failures than a changed value does.
The comparison here runs in the browser, which matters when the two files are API responses from two environments and one of them is production.
Almost certainly key order or formatting. Neither carries meaning in JSON, so a structural comparison ignores both and reports only real differences by path.
By position unless you know the order is meaningless. Set comparison will call two genuinely different documents identical when a list has been reordered.
Added and removed keys. A missing key explains more downstream errors than a changed value, and it is usually the faster route to the cause.