How to Compare Two JSON Documents Side-by-Side
When debugging API schema breaking changes, regression testing database migrations, or auditing snapshot updates, comparing JSON payloads with standard text diff tools produces false positives. Here is how semantic AST diffing works and how to accurately identify data mutations.
Why Text Diffs (Like diff --git a/webui.sh b/webui.sh old mode 100644 new mode 100755) Fail for JSON
Standard diff algorithms (such as the Myers diff algorithm used in Git) operate on raw lines of text. However, in the JSON specification (RFC 8259):
- Key ordering is non-deterministic:
{"a": 1, "b": 2}is semantically identical to{"b": 2, "a": 1}. A text diff flags this as two line removals and two additions. - Whitespace differences are meaningless: 2-space indentation vs 4-space indentation or minified JSON causes 100% line mismatch in text diff tools.
Semantic diffing first parses both inputs into structured object trees, sorts keys alphabetically at each depth level, and traverses nodes recursively by path (e.g. data.users[0].email). This isolates real value changes from superficial formatting differences.
The 4 Fundamental Types of JSON Mutations
| Mutation Type | Visual Indicator | Description |
|---|---|---|
| Added Key (Addition) | + ADDED (Green) | New property or array item present in the updated payload but absent in the base. |
| Removed Key (Deletion) | - DELETED (Red) | Property deprecated or removed from the base payload. |
| Modified Value (Mutation) | ~ MODIFIED (Yellow) | Path matches in both documents, but primitive values or data types differ (e.g. "100" vs 100). |
| Type Mismatch (Schema Breaking) | ! TYPE SHIFT (Purple) | A field changed from an Object to an Array or from a String to a Number. |
Running Side-by-Side Diffs with JSONLints Studio
To compare two payloads privately in real-time:
- Open JSONLints Studio and select the Diff tab.
- Paste your original JSON on the Left (Base) pane and modified JSON on the Right (Updated) pane.
- Click Compare Diff. The semantic diff engine highlights exact additions, deletions, and value shifts with line and column accuracy.
Unlike third-party diff servers that upload comparison payloads to their backend, JSONLints runs the entire AST traversal in your browser's local V8 runtime. Your API keys, customer payloads, and database dumps never leave your machine.