JSON Diff

Comparing two JSON documents

A text diff of JSON is noisy: reorder two keys or change indentation and every line looks changed even though the data is identical. A structural diff parses both sides and compares the actual values, then reports three things, keys added, keys removed, and values that changed, independent of formatting or key order.

Example

Old versus new:

old: { "name": "Ada", "role": "dev" }
new: { "name": "Ada", "role": "lead", "team": "core" }

~ role: "dev" -> "lead"
+ team: "core"

The ~ marks a changed value, + an addition. A removal would show as -. Because it compares parsed data, swapping the order of name and role produces no diff at all.

Where arrays complicate things

Objects compare by key, which is unambiguous. Arrays compare by position, which is not. Insert one element at the front of a list and a naive diff reports every following element as changed, even though they only shifted. Some tools try to match array elements by identity or a key field; most compare index by index, so be skeptical of large array diffs.

FAQ

Does key order ever matter? For comparison, no, two objects with the same keys are equal regardless of order. If order matters in your system, normalize first with JSON Sort Keys so a plain text diff becomes meaningful too.

How are types handled? 7 and "7" are different, a number versus a string, so a type change is reported as a changed value.

Is null equal to a missing key? No. A key present with value null differs from a key that is absent, and a good diff distinguishes the two.