JSON Diff

What it does

A diff of two JSON documents is a set of paths and two values per path. Object member order does not matter and array order does, which is the one convention worth stating because it is where diffs surprise people.

Parse both documents, walk them together, and report added, removed and changed paths. Member order is normalised; array indices are compared positionally.

Why it works this way

JSON objects are unordered by the specification, so a diff that reports a reordered member as a change is reporting a difference the data does not have. This one normalises order and says so.

Arrays are ordered, so an inserted element shifts everything after it and a naive diff reports the whole tail as changed. That is technically true and practically useless, which is why the counts are shown alongside the paths.

Identical documents must produce an empty list. That is the degenerate case with an answer nobody has to compute, and it is the one that catches a diff comparing a document with itself.

Examples

{"a":1,"b":2} vs {"a":1,"b":3}

changed: b  2 → 3

{"a":1,"b":2} vs {"b":2,"a":1}

no differences

Inputs and outputs

• left document
• right document

• the list of differing paths, with both values
• counts: added / removed / changed

Edge cases

• member order
• array insertion — the tail shifts and the counts show it
• null vs missing — different facts, reported separately
• number formatting: 1 vs 1.0 parse to the same value
• deep nesting

Sources

• RFC 8259, section 4 (Objects are unordered collections)