Structural vs Textual Comparison
A line-based tool such as diff reports every changed line, so re-indenting a file or reordering its keys shows up as a wholesale rewrite. A structural comparison parses both documents first and walks the resulting trees, so {"a":1,"b":2} and {"b":2,"a":1} are reported as identical. That is almost always what you want when the question is "what actually changed?".
What Gets Reported
- Added — a key path present in the second file only.
- Removed — a key path present in the first file only.
- Modified — the same key path with a different value or type.
Each result is labelled with its full path, such as user.address.city or items[2].price, so you can find it in the source file without hunting.
Arrays Are Compared by Position
JSON arrays are ordered, so element 0 is compared against element 0. Inserting a record at the front of a list therefore shifts every later element and reports a long run of modifications. When your arrays are really unordered sets keyed by id, sort both files by that id before comparing — the JSON Formatter's key sorting handles the object side of the same problem.
Comparing Files on the Command Line
# Normalise both, then diff — sorted keys, compact output
diff <(jq -S -c . a.json) <(jq -S -c . b.json)Who this guide is for
- Compare a config file before and after a deployment
- Check what changed between two versions of an API response
- Verify a migration produced the records you expected
- Review a pull request whose diff is buried in reformatted JSON