How to Compare Two JSON Files (Semantic Diff vs Text Diff)

Comparing two JSON documents with an ordinary text diff often produces a wall of red and green for changes that don't matter. Reordered keys, different indentation, or a minified file on one side are all differences in text but not in meaning. A JSON-aware diff compares the data itself.

Why text diffs are noisy

• Whitespace and formatting: the same data can be pretty-printed or minified.
• Key order: JSON objects are unordered, so {"a":1,"b":2} and {"b":2,"a":1} are equal.
• Number formatting: 1.0 and 1 may be the same value.
• Line-based tools report a whole line as changed even when a single value changed.

What a semantic diff reports

• Added: a key or array item present only in the new document.
• Removed: something present only in the old document.
• Changed: the same path holds a different value.
• Unchanged data is not shown, or is dimmed.

old: { "name": "Ada", "role": "user", "tags": ["a"] }
new: { "name": "Ada", "role": "admin", "tags": ["a", "b"], "active": true }

changed: role  "user" -> "admin"
added:   tags[1]  "b"
added:   active  true

Arrays are the hard part

Objects are compared by key, but arrays are ordered, so most tools compare them by index. Inserting an item at the start can make every following item look changed. If your arrays hold records with IDs, match items by ID rather than position.

Tips

1. 1Sort keys and format both files the same way first if you need a text diff.
2. 2Compare against the same environment or version; timestamps and IDs often differ legitimately.
3. 3Strip fields that always change, such as generated timestamps, before comparing.
4. 4For machine-readable changes, JSON Patch (RFC 6902) describes differences as a list of operations.