How to Compare Two JSON Files (and Actually See the Differences)

Diffing two JSON files directly often produces a wall of red and green even when almost nothing actually changed. The culprit is usually formatting, not content: different key order, different indentation, or one file minified and the other pretty-printed. Normalize both files first and the noise disappears.

Why JSON diffs look worse than they are

JSON objects have no defined key order - {"a": 1, "b": 2} and {"b": 2, "a": 1} represent exactly the same data. But a line-by-line text diff has no concept of that - it just compares characters, so a reordered key shows up as a removed line and an added line even though nothing meaningful changed. The same applies to whitespace: one file with 2-space indentation and the other minified onto a single line will diff almost entirely, regardless of whether the data differs at all.

Normalize then diff (the reliable recipe)

Put both files through the same formatter with the same key-sorting rule before comparing them. With Python:

python -m json.tool --sort-keys file1.json > file1.sorted.json
python -m json.tool --sort-keys file2.json > file2.sorted.json

Or with jq (the -S flag sorts object keys alphabetically):

jq -S . file1.json > file1.sorted.json
jq -S . file2.json > file2.sorted.json

Now both files use the same indentation and the same key order, so any remaining differences in a diff are real data changes rather than formatting artifacts. If you only need to know whether the underlying data is identical regardless of formatting, diff <(jq -S . file1.json) <(jq -S . file2.json) does the normalize-and-compare step in one line. If you work in an editor, the two .sorted.json files open just as well in VS Code's built-in diff view.

Step-by-step with the Text Diff tool

Once both files are normalized, open the two .sorted.json files (or paste their contents) into the Text Diff tool. Side-by-side view works well for shorter config-style JSON files; switch to unified view for longer files where you want changes and context interleaved in a single column. Enabling Ignore Whitespace catches any remaining indentation differences the normalization step missed.

Common gotchas

• Trailing commas are invalid JSON - a trailing comma after the last array or object item will make json.tool or jq fail to parse the file entirely. That parse failure is often the real bug, not a content mismatch.
• Number formatting can differ - 1.0 versus 1 represent the same value but serialize differently depending on the tool that produced the file, and will show up as a diff even though nothing changed numerically.
• Array order sometimes matters, sometimes doesn't - for an ordered list (steps, rankings) keep the order and diff normally. For an unordered set (tags, IDs) sort the array before diffing, or use a structural jq comparison, so a reordered-but-identical array doesn't register as a change.