The JSON Array Comparison Trap — Why Index Diff Breaks on Mid-Array Insertion

Guide · Last verified Aug 19, 2026

If you've compared two JSON documents, added just one item at the front of an array, and seen the diff show "changed" on dozens of lines, that's not the tool being broken — it's a scheduled side effect of the index-based comparison design. This guide explains, at the algorithm level, why JSON array diff works this way and why tools like git diff don't hit the same problem.

1. What index correspondence means

Comparing objects is simple because you match by key name. Compare {"name":"Alice"} and {"name":"Bob"} and you find the same key "name" and conclude only the value differs — done. But arrays have no names. What do you use to identify each element of ["a","b","c"]? The simplest solution is to treat the array index (0, 1, 2...) like an object key. That is, compare arr1[0] with arr2[0], arr1[1] with arr2[1], matching values only at the same position. It's simple to implement, fast, and has the advantage that even with nested objects or arrays it can recurse in at that position as-is.

2. Where it blows up: mid-array insertion

The fundamental weakness of index correspondence is that it can't distinguish "insertion" from "change." Adding an element at the very end of an array is displayed correctly as "added" with no problem. But when one element gets inserted in the middle of an array, every element after it shifts by one index. The index comparator doesn't understand this shift and, seeing that the value originally at index 1 is now at index 2, misinterprets it as "that value was changed to a different value."

3. How real diff tools avoid this: LCS

The algorithm Unix's diff command and git use for file comparison doesn't match indexes directly. Instead it first finds the Longest Common Subsequence (LCS). LCS is an algorithm that finds the longest part common to two sequences while preserving order (not necessarily contiguous). In the example above, ["a","b","c"] is the LCS as-is, so this algorithm produces the minimal, semantically correct diff: "a, b, c are commonly present as-is, and one x was inserted before them." The Myers diff algorithm git actually uses is a variant optimized to compute this LCS idea in O(ND) time. Pure LCS generally takes O(n×m) time, so compute cost grows noticeably as arrays get large.

4. Why JSON array diff tools don't use LCS

A lightweight browser-based JSON comparison tool has practical reasons for skipping LCS alignment. First, LCS fits strings and simple value arrays well, but when arrays contain objects it's ambiguous how to define "two objects are equal" (must they be fully identical, or equal on just certain fields?). Second, a large share of JSON arrays handled in practice are object arrays with a unique key like id, so the order often doesn't change much to begin with. Third, in the trade-off between compute complexity and implementation simplicity, a general-purpose JSON comparator often picks index comparison, which is "correct enough in most cases."

5. How to avoid this trap in practice

• If array elements are objects with a unique ID: pre-sort both arrays into the same ID order before running the diff and the index-shift problem disappears.
• If order itself doesn't matter for the array: sort both sides before comparing to eliminate order differences.
• If the array has frequent mid-insertions/deletions: a lot of "changed" in an index-based diff result is a normal signal, so rather than trusting the result as-is, eyeball once more which values actually changed.

Frequently Asked Questions