Blog Diff two JSON files without losing your mind

Diff two JSON files without losing your mind

2 min read

Diff two JSON files without losing your mind
TL;DR A raw diff of two JSON files drowns you in formatting and key-order noise. Normalise both first, sort keys and pretty-print with jq, then diff the normalised versions. Now the diff shows only the real changes in values and structure, not reordered keys.

Comparing two JSON files with a plain diff is a special kind of frustration. The data barely changed, but the diff is enormous, because the keys are in a different order, or the indentation differs, or one file has trailing whitespace. The trick is to normalise before you compare.

Why the raw diff lies

A text diff compares lines literally. It does not know that JSON is order-independent for object keys, or that whitespace does not matter. So two files with identical data but different key order or formatting look completely different to it. You get a wall of changes where nothing meaningful changed.

To see the real difference, you first make the two files line up on everything except content.

Normalise, then diff

Use jq to sort keys and pretty-print each file consistently, then diff the results:

jq --sort-keys . a.json > a.norm.json
jq --sort-keys . b.json > b.norm.json
diff a.norm.json b.norm.json

--sort-keys puts object keys in a consistent order in both files, and jq's formatting makes the indentation identical. Now diff compares the actual data, and what it shows you is what genuinely changed: a different value, an added or removed field, a real structural difference.

Do it in one line

You can skip the temp files with process substitution:

diff <(jq --sort-keys . a.json) <(jq --sort-keys . b.json)

Same result, nothing left on disk.

When you need more

For most cases, normalise-then-diff is enough. When you need a deeper, structure-aware comparison, arrays reordered, nested changes summarised, there are dedicated JSON diff tools that understand the format natively and can report changes as paths rather than lines. Reach for those when the jq-and-diff approach is not precise enough, which is rarer than you would think.

The point

The reason JSON diffs feel maddening is that you are comparing formatting, not data. Normalise both files, sort the keys, format them the same, and the noise vanishes, leaving only the changes you care about. It is a two-command habit that turns an unreadable diff into an obvious one, and it works on any JSON the terminal can reach.

FAQ

Why does diffing JSON files give so much noise?

Because a text diff compares lines literally, so different key order, indentation, or whitespace all show up as changes even when the data is identical. You end up with a huge diff where almost nothing actually changed.

How do I compare JSON by content, not formatting?

Normalise both files first, sort the keys and pretty-print them consistently, then diff the normalised output. jq can sort keys and format in one step, so the two files line up and only genuine differences remain.

Can I do this without a special tool?

Yes. jq plus the standard diff command is enough: pipe each file through jq with sorted keys, save the results, and diff them. For deeper structural comparison there are dedicated JSON diff tools, but the jq-and-diff approach handles most cases.