Two JSON documents can differ in one number and still look identical line by line. Comparing by path instead of by eye turns the difference into a short list.
A JSON diff is rarely about the whole file. It is about the one field that moved, the key that disappeared, or the value that changed type between two responses that were supposed to be the same.
Format first, then compare
Two files written by different tools can be identical as data and completely different as text: different indentation, different key order, different line breaks. Pretty-printing both sides before comparing removes the noise so the real difference is the only thing left.
Compare paths, not lines
Once both sides are parsed, the useful comparison walks them in parallel and reports the address of each difference: a path such as user.address.city rather than a line number. A path survives reordering and reformatting, so the same check stays meaningful the next time the payload changes.
- Added: a key exists on the right and not on the left.
- Removed: a key exists on the left and not on the right.
- Changed: the value at the same path is different.
- Type change: a value that was a number is now a string - the difference that breaks code quietly.
Keep only the difference you care about
Large payloads produce long reports. Filtering by a path prefix, or expanding only the branches that changed, keeps the answer on one screen where it can be read rather than scrolled.
Check the document parses before blaming the diff
A trailing comma, a single-quoted string or a duplicated key will fail before any comparison starts. Validating the document first separates a syntax problem from a data problem, which is usually the faster half of the debugging.