A plain text diff treats two JSON files as lines of text. That holds up until someone reformats one of them. Change the indentation or the key order and the text diff reports the whole file as changed, even though the data is identical. A JSON-aware diff compares the parsed structure instead, so reordered keys and whitespace don't show up as noise.
An example where text diff lies to you
// before
{ "id": 1, "name": "Ada" }
// after
{
"name": "Ada",
"id": 1
}Same data, different key order and formatting. A line-based diff flags this as a full rewrite. A structural diff reports no changes.
Array order does matter
Object key order carries no meaning in JSON: {"a":1,"b":2} and {"b":2,"a":1} are the same value. Array order is different. [1, 2, 3] and [3, 2, 1] are different values, and a good diff tool treats them that way. Reordering array elements should show up as a change. Reordering object keys shouldn't.
Type coercion hides bugs
Take {"count": "5"} vs {"count": 5}, a string against a number. A tool that loosely coerces types before comparing reports no change here. This is one of the most common API contract drift bugs: an endpoint used to return a number, a refactor started serializing it as a string, and every consumer that compares that field numerically breaks without an error. A strict diff should flag the type change even when the “value” looks the same.
What to look for in the output
You want added, removed, and changed entries expressed as JSON paths (user.address.zip, rather than “line 14”). A path tells you where in a nested structure something moved. A line number makes you work that out again by hand.