Canonicalize first with the JSON Formatter, then compare with the Text Diff Tool.
Why text diff lies about JSON
JSON is a data format, not a text format. Two documents can be semantically identical yet look completely different as text: different key order, indentation, spacing, or escaped characters.
A line-based text diff highlights every one of those cosmetic differences. Reviewing an API response change becomes a wall of red and green lines even when the only real change was one field.
Text diff answers the question 'which characters differ?' JSON diff answers the question 'which data changed?' - and for configuration, API responses, and test fixtures, that is the question you actually care about.
When text diff is the right tool
- You are reviewing generated JSON and want to see formatting changes too
- You suspect invisible characters, encoding, or whitespace differences
- The files are small and key order is meaningful to your tooling
- You are diffing a log excerpt or JSON embedded in a larger text file
When semantic JSON diff is the right tool
- Comparing API responses between deployments or environments
- Reviewing configuration changes where key order is irrelevant
- Checking whether two generated files are equivalent after a formatter ran
- Writing tests that should fail on real data changes, not on formatting
Compare JSON semantically, step by step
- Open the JSON Formatter and paste the first document.
- Format and minify the result to normalize key order and spacing.
- Repeat for the second document.
- Open the Text Diff Tool and paste the two normalized versions.
- Review the diff - now every difference is a real data difference.
Note: Normalizing key order before diffing is the essential trick. Once both sides use the same key order and spacing, a text diff becomes a cheap and accurate semantic diff.
When order itself is the data
JSON arrays are ordered - [1,2,3] and [3,2,1] are different values. A semantic diff must compare arrays positionally, which a naive key-sorting approach can get wrong.
For APIs and configs, that is correct behavior. If your application treats object keys as ordered (some tools do), the textual comparison is the honest one.
Standards like JSON Patch and JSON Merge Patch formalize change representation: JSON Patch is a list of add/remove/replace operations, JSON Merge Patch is a partial document. Understanding which one your API expects removes a whole class of diff confusion.
Text diff vs JSON diff at a glance
| Question | Text diff | Semantic JSON diff |
|---|---|---|
| Did the bytes change? | Yes - shows every byte difference | Only if the data changed |
| Did the data change? | Noisy, depends on formatting | Yes - precise |
| Key order changes | Shown as a change | Ignored (objects are unordered) |
| Array element moves | Shown as a change | Shown - arrays are ordered |
| Whitespace / indentation | Shown | Ignored |
FAQ
Q.Why does my JSON diff show changes I did not make?
A.Almost always because the two files differ in key order, indentation, or trailing whitespace. Normalize both sides with a formatter and re-diff to see the real data change.
Q.Does JSON care about key order?
A.Per RFC 8259, JSON objects are unordered collections of name/value pairs. Most parsers and APIs treat them that way, so semantic comparison ignores key order - unless your tooling explicitly relies on it.
Q.Are arrays compared positionally?
A.Yes. JSON arrays are ordered, so [1,2] and [2,1] are different. A good diff tool compares them by index, and optionally detects moved elements for readability.
Q.How do I review an API response change?
A.Capture the response before and after, canonicalize both with a formatter, and diff them. You will immediately see added, removed, or changed fields without being distracted by formatting noise.
Q.Can I compare JSON schemas the same way?
A.Yes, but schemas are documents where key names carry meaning, so treat them as ordered data or use a schema-aware comparison. For a quick review, canonicalize and diff exactly as described above.
References
- RFC 8259 – The JavaScript Object Notation (JSON) Data Interchange Format: https://www.rfc-editor.org/rfc/rfc8259
- RFC 6902 – JavaScript Object Notation (JSON) Patch: https://www.rfc-editor.org/rfc/rfc6902
- RFC 7386 – JSON Merge Patch: https://www.rfc-editor.org/rfc/rfc7386
Compare JSON cleanly
Canonicalize with the JSON formatter, then diff locally in your browser.
Pick the diff that answers your question
Text diff finds byte changes; semantic JSON diff finds data changes. For configuration and API work, normalize first, then diff - and you get both cheaply.
Format with the JSON Formatter and compare with the Text Diff Tool, both client-side.