How to Compare Two JSON Files (Semantic Diff vs Text Diff)

Comparing two JSON documents with an ordinary text diff often produces a wall of red and green for changes that don't matter. Reordered keys, different indentation, or a minified file on one side are all differences in text but not in meaning. A JSON-aware diff compares the data itself.

Why text diffs are noisy

• Whitespace and formatting: the same data can be pretty-printed or minified.
• Key order: JSON objects are unordered, so {"a":1,"b":2} and {"b":2,"a":1} are equal.
• Number formatting: 1.0 and 1 may be the same value.
• Line-based tools report a whole line as changed even when a single value changed.

What a semantic diff reports

• Added: a key or array item present only in the new document.
• Removed: something present only in the old document.
• Changed: the same path holds a different value.
• Unchanged data is not shown, or is dimmed.

old: { "name": "Ada", "role": "user", "tags": ["a"] }
new: { "name": "Ada", "role": "admin", "tags": ["a", "b"], "active": true }

changed: role  "user" -> "admin"
added:   tags[1]  "b"
added:   active  true

Arrays are the hard part

Objects are compared by key, but arrays are ordered, so most tools compare them by index. Inserting an item at the start can make every following item look changed. If your arrays hold records with IDs, match items by ID rather than position.

Tips

1. Sort keys and format both files the same way first if you need a text diff.
2. Compare against the same environment or version; timestamps and IDs often differ legitimately.
3. Strip fields that always change, such as generated timestamps, before comparing.
4. For machine-readable changes, JSON Patch (RFC 6902) describes differences as a list of operations.

Private data

API responses and configs often include secrets or personal data. Use a diff tool that runs in your browser so neither document is uploaded.

Frequently asked questions

How do I compare two JSON files?

Paste both into a JSON diff tool, which compares the data structure and highlights added, removed, and changed values.

Does key order matter in JSON?

No. JSON objects are unordered, so a semantic diff ignores key order. Array order does matter.

What is JSON Patch?

A standard (RFC 6902) format that describes changes between two JSON documents as a list of add, remove, and replace operations.

Why does my diff show every array item changed?

An item was likely inserted or removed near the start, shifting positions. Match records by a unique ID instead of by index.

Try it: JSON Diff — free, runs in your browser, nothing is uploaded.

Originally published at ilovekit.app.