Why structural comparison beats line-by-line text diffing for JSON

JSON has no canonical formatting — the same data can be pretty-printed with different indentation, minified onto one line, or have its object keys in a different order, and all of those are exactly equivalent as data even though they'd look completely different to a plain text diff. Comparing the parsed values instead of the raw text means whitespace, formatting, and key order never produce a false-positive difference — this tool only reports a change when the actual data at a given path genuinely differs, which is what "did this API response change" or "did this config actually change" really means in practice.

Why array insertions look like a cascade of changes

This tool compares arrays by index — element 0 against element 0, element 1 against element 1, and so on — rather than trying to detect that an element was inserted or removed and realign the rest. That means inserting a single new item in the middle of an array shifts every subsequent element's index, which shows up here as "every element after the insertion point changed" rather than a single clean insertion. That's a real tradeoff, not a bug: true sequence-alignment diffing (the kind `git diff` does for text) is a fundamentally different, more expensive algorithm, and for the common case of comparing API responses or config structures, index-based comparison is usually both simpler to reason about and sufficient — most changes to a JSON array are value edits or additions at the end, not mid-array insertions.