How to Compare Two JSON Files
You have two versions of a config, two API responses or two exports, and you need to know what changed. A normal text diff often gives a useless answer for JSON: it flags hundreds of lines when only one value changed. This guide shows why, and how to compare JSON the right way: by structure.
Why text diff fails on JSON
These two documents contain exactly the same data:
{"name":"app","version":"1.0","limits":{"users":10}}{
"version": "1.0",
"limits": { "users": 10 },
"name": "app"
}A text diff reports every line as changed, because the formatting and key order differ. Neither matters in JSON: object keys have no order. You want a diff that compares values, not characters.
Structural diff: compare the data
A structural diff parses both documents and walks through them, reporting only real differences, each with its exact path:
CHANGED $.version "1.0.0" โ "1.1.0"
ADDED $.features[2] "export"
CHANGED $.limits.users 10 โ 25
REMOVED $.limits.storage "5GB"
ADDED $.beta trueThat is what JSON Diff does. Paste the original on the left and the new version on the right, and it lists every added, removed and changed value with counts. Formatting and key order are ignored.
The tricky part: arrays
Arrays do have an order, so they are compared position by position. That is correct for most data, but it has one consequence: if an item is inserted at the start of a list, every following item appears "changed", because each one moved one position.
When the order of a list doesn't matter, sort both lists by a stable key (such as an ID) before comparing. With jq:
jq '.users |= sort_by(.id)' old.json > old.sorted.json
jq '.users |= sort_by(.id)' new.json > new.sorted.jsonCommand line: jq + diff
jq can normalize both files: -S sorts keys, and formatting becomes identical. Then any regular diff tool works:
diff <(jq -S . old.json) <(jq -S . new.json)
# or with git's colored, word-level diff
git diff --no-index --word-diff <(jq -S . old.json) <(jq -S . new.json)This is a good choice for scripts and CI pipelines. The output shows lines rather than paths, but the noise from formatting and key order is gone.
In code
Checking whether two documents are equal is built in:
import { isDeepStrictEqual } from 'node:util'
isDeepStrictEqual(JSON.parse(a), JSON.parse(b)) // true/false, key order ignoredimport json
json.loads(a) == json.loads(b) # dict key order ignored, list order mattersTo list the differences, use a library such as deepdiff for Python, or jsondiffpatch or microdiff for JavaScript.
Common uses
- API changes: compare a response before and after a deployment to catch removed or renamed fields.
- Config drift: compare the staging and production configs.
- Test failures: see exactly which field differs between the expected and actual output.
- Data exports: find which records changed between two days.
Related
- JSONPath tutorial: understand paths like
$.limits.users - How to pretty print JSON