Comparing JSON Files: What to Watch Out For

Why JSON Diffs Can Be Misleading

If you paste two JSON files into a standard text diff tool and they both represent exactly the same data, you might still see differences flagged. This happens for a few reasons worth understanding before you start comparing.

Key ordering

JSON objects ({ }) are technically unordered — the specification says that key order has no defined meaning. However, in practice, different tools, languages, and serialisers often output keys in different orders. A Python script that generates JSON may sort keys alphabetically; a JavaScript tool might output them in insertion order; a Java library might order them differently again.

The result: two JSON files that are semantically identical but have keys in different orders will show as almost entirely different in a plain text diff, even though the data they represent is exactly the same. If you're comparing JSON outputs from two different systems, this is the first thing to check.

Whitespace and formatting

"Minified" JSON has all whitespace stripped out — no line breaks, no indentation. "Pretty-printed" JSON is formatted for human readability with indentation and newlines. These two representations contain identical data, but a text diff will flag virtually every character as different. Before diffing JSON files, normalise both to the same format first.

Number representation

Some serialisers output 1.0 where others output 1. Some output 1e3 where others output 1000. These are numerically identical but will show as differences in a text diff.

Unicode and encoding

JSON can represent non-ASCII characters either directly (e.g. "café") or as Unicode escape sequences (e.g. "caf\u00e9"). Both are valid JSON and represent the same string, but a text diff will flag them as different.

When a Plain Text Diff Is Enough

Despite the caveats above, a plain text diff is often exactly what you want for JSON files. If you're comparing two files produced by the same tool or system, they'll typically have consistent formatting and key ordering. A text diff will give you an accurate picture of what actually changed.

Text diffs are also better than semantic JSON diffs when you care about the exact bytes in the file — not just the represented data. If you're verifying that a deployment didn't alter a configuration file, or checking that a backup matches the original, text-level comparison is what you need.

For these cases, TextFileCompare's JSON mode works well. It applies syntax highlighting to both panels so the structure is visually clear, and the word-level diff makes it easy to spot exactly which values changed within a line.

Preparing JSON Files for Comparison

1. Validate both files first

A malformed JSON file will look different from a valid one in ways that have nothing to do with the data. You can validate JSON quickly using python3 -m json.tool yourfile.json in a terminal, or any online JSON validator.

2. Normalise formatting

If the files might have different indentation or whitespace, run them both through the same formatter first. In Python:

import json
with open('file.json') as f:
    data = json.load(f)
print(json.dumps(data, indent=2))

Paste the output of this rather than the raw file into your diff tool, and both files will be on a level playing field for whitespace.

3. Sort keys if ordering varies

If the files were produced by different systems and might have keys in different orders, use sort_keys=True in Python's json.dumps. This makes the comparison focus on data differences, not ordering differences.

Real-World JSON Comparison Scenarios

Comparing API responses

You've called the same API endpoint in two environments — staging and production — and want to verify the responses match. Paste both into TextFileCompare, set the language to JSON, and run the diff. Word-level highlighting will show you exactly which values differ, even if they're buried in a large response object. Watch for differences in timestamps, IDs, or session tokens — these will legitimately differ between calls and aren't real discrepancies.

Diffing package.json or package-lock.json

After running npm install or npm update, comparing the old and new package-lock.json shows exactly which dependency versions changed. Lock files can be very large — TextFileCompare handles this well, and the chunk navigation lets you jump through changes without scrolling through thousands of lines manually.

Validating a data transformation

You have a script that transforms a JSON data file. After running the script, diffing the input and output JSON shows exactly what the transformation did. If the diff shows changes you didn't expect, you've found a bug.

Comparing configuration files across environments

Many applications use JSON for configuration: Firebase config, VS Code settings, ESLint rules, Prettier config. Comparing production and development config files shows what differs between environments. TextFileCompare is safe for sensitive config since everything stays in your browser.

Using TextFileCompare With JSON

When you load a .json file into TextFileCompare by upload or drag-and-drop, the tool automatically detects the file extension and applies JSON syntax highlighting. You can also manually select JSON from the language dropdown if you're pasting content without uploading a file.

For most JSON comparison tasks, the workflow is: paste or upload both files, click Compare, and use the Previous/Next buttons to navigate through the differences. The word-level highlighting within changed lines means you'll see exactly which value changed, not just that a line changed.