How to Compare Two JSON Files

Choose semantic comparison when the data matters more than the text

A plain text diff compares characters and lines. That is useful for source-control history, but whitespace, indentation and object-property order can produce a noisy diff even when the represented data is effectively unchanged.

A JSON-aware diff parses both documents and compares paths and values. This makes it easier to answer the questions developers usually care about: what was added, what disappeared and which existing value changed.

Work from a concrete before-and-after example

Suppose an API plan changed from free to pro. A structural diff should identify the changed plan, changed limits and added trial field rather than report an entire reformatted block as different.

Original:
{"plan":"free","limits":{"projects":3,"seats":1}}

Updated:
{"plan":"pro","limits":{"projects":25,"seats":3},"trial":false}

Meaningful changes:
plan: "free" → "pro"
limits.projects: 3 → 25
limits.seats: 1 → 3
trial: added false

Classify changes as added, removed or changed

Grouping differences by change type makes reviews faster. Added paths can signal new API fields, removed paths can indicate a breaking contract change, and changed values can reveal configuration drift or behavioral differences.

• Added: the path exists only in the updated document.
• Removed: the path exists only in the original document.
• Changed: the same path exists in both but has a different value or JSON type.
• Type change: treat 42 and "42" as different even when they look similar on screen.

Object key order and array order are different problems

Object property order generally should not define semantic equality for JSON data, although an application can choose to preserve insertion order for display. Arrays are sequences, so position is normally significant.

Reordering an array can therefore produce several changes even if it contains the same members. Before normalizing array order, decide whether your domain treats the array as an ordered list or as an unordered set keyed by an identifier.

These objects normally represent the same mapping:
{"a":1,"b":2}
{"b":2,"a":1}

These arrays are normally different sequences:
["draft","published"]
["published","draft"]

Normalize only the differences you know are irrelevant

Formatting both inputs can remove whitespace noise. Sorting object keys can also help text-based review when key order is irrelevant. Avoid automatically sorting arrays or converting numeric strings to numbers unless the application contract explicitly treats those transformations as equivalent.

Over-normalization can hide real bugs. A user ID of "00123" is not necessarily equivalent to the number 123, and a reordered priority list can change application behavior.

Compare API responses with contract changes in mind

When comparing API responses, separate expected nondeterministic fields from contract changes. Timestamps, request IDs and generated links can change on every call, while a removed required property or changed type may break consumers.

For repeatable tests, normalize only known volatile fields and keep the rest of the response strict. Pair structural comparison with JSON Schema or contract tests when compatibility matters.

Compare configuration without hiding environment-specific values

Configuration diffs often contain legitimate environment differences alongside accidental drift. Flattened paths can make nested settings easier to review because each key becomes a direct path such as database.pool.max or featureFlags.checkout.

Redact secrets before copying configuration into tickets or external tools. JSON Hearth processes data locally in the browser, but screenshots, clipboard history and exported files can still expose sensitive values outside the tool itself.

A safe JSON comparison workflow

Open JSON Compare & Diff, place the original document on the left and the candidate document on the right, then review every reported path. If a difference looks like formatting noise, verify that the underlying values truly match before discarding it.

• Validate both documents first so syntax errors do not masquerade as differences.
• Use structural comparison for nested data and text diff for exact source changes.
• Review array semantics before sorting or treating reordered elements as equal.
• Check value types as well as visible text.
• For important contracts, convert accepted differences into automated tests.