A plain text diff on two JSON files treats them as lines of text. That works until someone reformats one of them — different indentation, different key order — and suddenly a text diff shows the entire file changed even though the data is identical. A JSON-aware diff compares the parsed structure instead, so key reordering and whitespace differences 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 text diff will flag this as a full rewrite. A structural diff correctly reports no changes.
Array order actually matters, though
Object key order is semantically meaningless in JSON — {"a":1,"b":2} and {"b":2,"a":1} are the same value. Array order is not meaningless. [1, 2, 3] and [3, 2, 1] are genuinely different values, and a good diff tool needs to treat them that way — reordering array elements should show up as a real change, unlike reordering object keys.
Type coercion hides real bugs
{"count": "5"} vs {"count": 5} — a string versus a number. If your comparison tool loosely coerces types before comparing, this looks like no change. It's actually one of the most common real bugs in API contract drift: an endpoint used to return a number, a refactor accidentally serialized it as a string, and every consumer that does numeric comparison on that field silently breaks. A strict diff should flag type changes even when the “value” looks the same.
What to actually look for in the output
Added, removed, and changed paths, expressed as JSON paths (user.address.zip, not just “line 14”), so you know exactly where in a nested structure something moved — that's the difference between a diff you can act on and one you have to re-derive by hand.