How to compare two JSON files

August 28, 2026 · 13 min read

Diffing two .json files as plain text wastes time: key order, indentation, and trailing newlines create noise. The reliable approach parses both files into values, optionally normalizes them, then compares structure. This guide covers manual review and automation patterns.

Parse before you diff

Run both files through a strict JSON parser. Invalid JSON must fail fast with line numbers - fix syntax before hunting semantic differences. The JSON validator catches trailing commas and bad escapes quickly.

Normalize inputs

Sort object keys recursively if order should not matter.
Choose whether null and missing keys are equivalent for your domain.
Round floats to a fixed precision if APIs emit inconsistent decimal places.

jq -S . file-a.json > a.norm.json
jq -S . file-b.json > b.norm.json
diff a.norm.json b.norm.json

Semantic compare

Structural diff tools report paths like root.items[2].price changed from 9.99 to 10.99. That is what you want in code review - not a wall of line changes from reformatting.

Browser workflow

Open the JSON compare tool, paste or drop contents from each file, and read the structural report. Ideal for support tickets and one-off API debugging when you do not want to commit temp files to the repo.

Automate in CI

Store golden fixtures in git and assert deep equality in tests. For large snapshots, consider dedicated diff libraries that output junit-friendly reports. Humans use browser compare; pipelines use code.

FAQ

Will diff ignore key order?: Only if your tool compares parsed objects. Text diff on files does not ignore key order unless you normalize first.
How do I compare JSON arrays where order matters?: Use index-sensitive array compare; do not sort arrays before diff unless business rules say order is irrelevant.

Browse all tools