Text diff vs JSON compare: which one to use for JSON files
By TechCompare · Updated · How we check
Use a text diff when the exact text matters, like a config in version control or a patch. Use a JSON compare when you want to know which values changed, whatever the key order or formatting.
The example
3 changes: 2 lines removed, 2 added
| Original: package.json | Changed: package.json | ||||
|---|---|---|---|---|---|
| 1 | { | 1 | { | ||
| 2 | Added | "debug": false, | |||
| 2 | "name": "api", | 3 | "name": "api", | ||
| 3 | Removed | "version": "1.4.0", | |||
| 4 | "port": 8080, | 4 | "port": 8080, | ||
| 5 | Removed | "debug": false | 5 | Added | "version": "1.5.0" |
| 6 | } | 6 | } | ||
There are two ways to compare JSON files. A text diff compares lines, so it shows exactly how the files differ as text. A JSON compare reads both files as data first, so it shows how the values differ. The two answers can look very different for the same pair of files, and each one is right for its own question.
How this is calculated
In the example, a small package file was saved by a tool that sorts keys, and the version went from 1.4.0 to 1.5.0. The data change is one value. A text diff reports 3 changes: 2 lines removed, 2 added, because debug moved to the top and version moved to the bottom. The moved lines show up as removed in one place and added in another.
A JSON compare reads the same two files and reports a single change at $.version, from "1.4.0" to "1.5.0". Key order doesn't count in JSON, since RFC 8259 defines an object as an unordered collection of names and values. Whitespace between values doesn't count either.
So which one is right? It depends on the question:
- "Did the data change?" is a JSON question. Use the JSON Formatter's compare mode, which also lines up arrays and compares numbers by value.
- "What exactly will this commit change in the file?" is a text question. The reordered keys are part of the commit, and a reviewer should see them.
- "Can I send this change as a patch?" is a text question too. A patch describes lines, and a list of JSON paths can't be applied with
git apply.
To make a text diff of JSON readable, format both files the same way before you compare them. jq -S . file.json sorts the keys and indents with two spaces, so after running it on both files only the real changes are left.
Verdict
For JSON, start with the JSON compare to learn which values changed, then use the text diff when you need to review or ship the exact file. If the text diff is full of moved keys, sort and format both files the same way and compare them again.
More Text Diff scenarios
Related guides
Frequently asked questions
Why does a text diff show changes when my JSON data is the same?
Can I apply a JSON compare result as a patch?
Related tools
JSON Formatter
Validate, format, and minify JSON. Browse it as a tree, run JSONPath queries, compare two documents, or validate against a JSON Schema.
Use toolCharacter Counter
Count characters, words, sentences, paragraphs, and lines. Check writing limits and count specific characters or phrases.
Use toolText Encoding Converter
Convert text to Base64, binary, hex, URL encoding and HTML entities, and back again.
Use tool