Understanding JSON Diff: Comparing Data Structures
Diffing two JSON documents sounds simple until you try it. A naive text diff flags reordered keys and reformatted whitespace as changes, drowning the real differences in noise. A structural diff understands the data.
Text diff vs. structural diff
A text diff compares documents line by line — exactly what git does. It's great for source code, but for JSON it's fooled by formatting. A structural diff instead compares values by their key path, so it reports a change only when a value truly differs.
Additions, removals, and changes
A good JSON diff classifies every difference: keys that were added, keys that were removed, and values that changed. Color-coding these git-style — green, red, and amber — lets you scan a large comparison in seconds.
- Added: a key present in the new document but not the old.
- Removed: a key present in the old document but not the new.
- Changed: a key whose value differs between the two.
Order independence
Because object keys in JSON have no guaranteed order, a structural diff should treat { a: 1, b: 2 } and { b: 2, a: 1 } as identical. This is the single biggest advantage over a plain text comparison.
Try it yourself
Compare two JSON objects side by side and see exactly what was added, removed, or changed.