One Array Shift Can Read as Several Differences

You prepend one element to an array and the comparison comes back with several changed paths. That answer can be correct. Whether it is depends on what the comparison tracks: zero-based positions, item identity, or membership in an unordered set. Those are three different questions, and a diff tool cannot infer which one you meant from the document alone.

The rule this tool applies: positional, zero-based

Before: {"steps":["build","test"]}
After: {"steps":["lint","build","test"]}

Expected differences:

  • Changed $["steps"][0]: “build” → “lint”
  • Changed $["steps"][1]: “test” → “build”
  • Added $["steps"][2]: (absent) → “test”

Run the array-insertion example →

JSON Compare walks each zero-based index. It does not label a change as a move, does not search for a matching identifier, and does not collapse the array to a set. For build pipelines and execution orders, position often is the meaning, so a positional diff states plainly what happened at every step.

Objects play by another rule

Object keys compare by their decoded names, whatever order they appeared in. Paths use JSON-quoted bracket notation, so keys containing dots, quotes or spaces stay unambiguous. Added or removed subtrees report at the path where they enter or leave the document, and changing a value’s type counts as one change at that path.

Before: {"name":"worker","count":1e3}
After: {"count":1000,"name":"worker"}
Expected: no structural differences.

Numbers compare as exact decimals, so 1e3 equals 1000. Key order is presentation, not structure. Arrays are the only place where order carries meaning, and that is exactly where a one-element edit becomes several honest, individually correct changes.

When identity-based comparison fits

There are datasets where positional diffing over-reports: event lists keyed by an id field, or configuration arrays where order is cosmetic. In those cases a diff that reports three changes for one logical edit is accurate about positions but noisy about intent. The right response is not to change the tool but to name the comparison in the contract: “this list compares by position” belongs next to the field in the schema, exactly like a type declaration.

Reviewers can reproduce the expected output in seconds with the compare tool: paste both documents, read the per-index report, and either accept the three changes as truth or write the identity rule down where the next engineer will find it.