{} JSON Diff — Compare Two JSON Objects Online

Complete Guide: JSON Diff

Comparing two JSON objects is fundamentally different from comparing two text files. A naive text diff will flag differences that don't actually exist semantically, and miss type-coercion traps that do matter. Understanding these distinctions makes JSON diffing a powerful tool for API testing and data validation.

Why JSON Diff Is Different from Text Diff

Consider these two JSON strings:

// Version A
{"name": "Alice", "age": 30}

// Version B
{"age": 30, "name": "Alice"}

A text diff will report these as completely different — every line changed. A semantic JSON diff recognizes them as identical, because JSON objects are unordered collections of key-value pairs. Key order is irrelevant to the data structure. This is the core insight that separates JSON-aware diffing from plain text comparison.

Semantic Equality Rules

Two JSON values are semantically equal when:

• Objects: they have the same keys with recursively equal values (order irrelevant)
• Arrays: they have the same length and elements are equal at each index (order IS significant for arrays)
• Primitives: numbers, strings, booleans are strictly compared — "1" (string) does NOT equal 1 (number)
• Null: null equals null only; it does not equal false, 0, or ""

Type coercion is a common trap: if your API returns "count": "5" instead of "count": 5, a semantic diff will correctly flag this as a type change even though the values look the same as text.

RFC 6902: JSON Patch Format

RFC 6902 defines a standard format for expressing the difference between two JSON documents as a sequence of operations. This is the format JSON Diff tools often output:

[
  { "op": "replace", "path": "/user/name", "value": "Bob" },
  { "op": "add",     "path": "/user/email", "value": "bob@example.com" },
  { "op": "remove",  "path": "/user/phone" }
]

Operations include: add, remove, replace, move, copy, and test. JSON Patch documents can be applied programmatically to transform one document into another, making them useful for partial updates in REST APIs (PATCH method).

Deep Equality Algorithms

Deep equality checks recursively compare nested structures. The key implementation considerations are:

1. Circular reference handling — naive recursion will stack overflow on circular structures. Production implementations track visited object references.
2. Special number values — NaN !== NaN in JavaScript's strict equality, but most JSON diff tools treat two NaN values as equal.
3. Prototype chain — JSON objects should be compared on own enumerable properties only, not inherited properties.

API Contract Testing

JSON Diff is indispensable for API contract testing: verifying that an API response still matches its documented schema after a code change. Tools like Dredd, Pact, and Postman test runners use semantic JSON comparison to validate responses. A common workflow:

1. Capture a "golden" response from a known-good API version
2. Run your test suite against the new version
3. Use JSON Diff to compare actual vs expected, ignoring dynamic fields like timestamps and IDs

Comparing MongoDB Documents

MongoDB stores data as BSON (Binary JSON). When comparing documents retrieved from MongoDB, be aware that BSON has additional types not in standard JSON: ObjectId, Date, NumberLong, Decimal128. When serialized to JSON for comparison, these are typically represented as objects like {"$oid": "..."} or {"$date": "..."}. Your diff tool must handle these representations consistently.

CI Snapshot Testing

Snapshot testing stores a "snapshot" of a component's output and fails the test if the output changes unexpectedly. For JSON-returning APIs or functions, semantic JSON snapshots are more robust than text snapshots: reformatting or key reordering won't break your tests. Libraries like Jest's toMatchSnapshot() use deep equality for object snapshots.

For formatting and validating JSON before diffing, use our JSON Formatter. For text-based comparisons, see Diff Checker.