Why JSON Array Diffing Is Harder Than It Looks

Chaitanya Chandurkar — Thu, 10 Sep 2026 08:00:43 +0000

Change one field in a JSON object, then reorder the surrounding array. A diff can suddenly report that nearly every record changed.

Many JSON diff tools compare arrays by position. That is exactly right for arrays whose order carries meaning. But when an array represents a collection of records, positional matching can produce a surprising amount of noise.

Consider these two payloads:

Original

{
  "users": [
    { "userId": 101, "name": "Alice", "role": "engineer", "status": "active" },
    { "userId": 102, "name": "Bob", "role": "engineer", "status": "active" },
    { "userId": 103, "name": "Carol", "role": "manager", "status": "active" }
  ]
}

Changed

{
  "users": [
    { "userId": 103, "name": "Carol", "role": "manager", "status": "active" },
    { "userId": 101, "name": "Alice", "role": "engineer", "status": "active" },
    { "userId": 102, "name": "Bob", "role": "engineer", "status": "inactive" },
    { "userId": 104, "name": "David", "role": "designer", "status": "active" }
  ]
}

A positional comparison pairs the first object on the left with the first object on the right, then the second with the second, and so on. Since Carol moved to the beginning, several unchanged users appear to have been modified.

But a person looking at this data would probably describe only two meaningful changes:

Bob's status changed from active to inactive.
David was added.

The records didn't lose their identity just because their positions changed.

The users are paired by userId, so reordering is not reported as a modification.

I built JSON Semantic Diff to explore a different approach: try to identify corresponding records before comparing their fields.

The real problem is correspondence

Once two objects have been paired correctly, comparing their fields is straightforward. The difficult question is which object on the left corresponds to which on the right.

It is tempting to solve this by looking for a field named id. Real payloads rarely make it that simple.

An identity might be called:

id
userId
orderNumber
sku
email
something specific to the domain

And sometimes no single field is enough.

Field names are also not proof. A field called id can be missing, duplicated, regenerated between responses, or only unique in the tiny sample currently being compared. Conversely, an unfamiliar field may be the most reliable identity in the data.

So JSON Semantic Diff treats a promising name as a hint, not a rule.

Trying to infer identity from the data

For each array of objects, the matcher examines individual fields and field combinations as possible identities. It evaluates each candidate using measurable signals:

Signal	What it asks
Uniqueness	Does the candidate distinguish records within each input?
Match coverage	How many records can be paired across the two inputs?
Population overlap	Does the overlap represent enough of both arrays?
Completeness	Is the candidate present on the records being compared?
Type consistency	Are its values represented consistently?
Name hint	Does the field name weakly suggest identity?

These signals answer different questions. A candidate can be unique but useless if none of its values appear in the other document. It can have matching values but cover only a tiny fraction of a much larger array. A familiar field name can help break a close tie, but it should not rescue an otherwise weak candidate.

The signals are combined into a candidate score. There is also a small complexity penalty for composite candidates, so a single reliable field is preferred to an unnecessarily complex combination.

The selected identity scored 94%, beating the second candidate by a 14.3-point margin.

A high score alone is not enough. Automatic matching must also pass safety gates for uniqueness, cross-input coverage, and the margin over the second-best candidate.

That last check matters. If two identities receive nearly identical scores, choosing either one may be arbitrary. A matcher that confidently makes the wrong pairing is worse than a positional diff because its output looks clean while hiding an incorrect assumption.

Some records need a composite identity

Inventory data is a good example. Imagine records shaped like this:

{
  "inventory": [
    { "store": "BOS", "sku": "SKU-1001", "quantity": 24, "price": 12.99 },
    { "store": "NYC", "sku": "SKU-1001", "quantity": 13, "price": 12.99 },
    { "store": "NYC", "sku": "SKU-2004", "quantity": 11, "price": 8.50 }
  ]
}

store is not unique because each store carries many products. sku is not unique because the same product exists in many stores. Together, however, sku + store can identify one inventory record.

After records are paired by that composite identity, the diff can distinguish between:

an existing product whose quantity changed,
an existing product whose price changed,
a newly added store-product combination, and
records that only moved to another array position.

Neither sku nor store is sufficient by itself, but the combination identifies an inventory record.

Composite inference expands the search space and increases the chance of finding accidentally unique combinations. That is why candidate complexity is penalized and why coverage and population overlap remain important.

When inference is ambiguous

Not every array contains a reliable identity.

Values may be duplicated. Too few records may overlap. A field may be missing on part of the array. Two candidates may be almost equally plausible. Some arrays are genuinely ordered sequences and should be compared by position.

When the evidence is not strong enough, JSON Semantic Diff falls back to positional matching.

You can then manually select one or more identity fields when domain knowledge provides information the payload alone cannot establish. Automatic inference should save work when the evidence is strong, without taking control away when it is not.

Deterministic and explainable by design

No AI model or fuzzy semantic matching is involved. Given the same inputs and configuration, the matcher produces the same decision.

The interface exposes the selected candidate, its score, the component signals, the runner-up, and the margin between them. That makes it possible to ask not only what did the matcher choose? but why did it choose this?

The comparison also runs locally in the browser. The JSON does not need to be uploaded to a server, which is useful when inspecting internal API responses, configuration, test fixtures, or production-shaped data.

A cleaner diff needs a cautious matcher

A semantic diff is not merely a prettier rendering of a positional diff. It makes an additional claim about correspondence:

These two records represent the same entity, even though they occupy different positions.

That claim can remove a large amount of noise, but only when it is well supported. The goal is not to infer an identity as often as possible. It is to recognize when the evidence is strong enough to trust one, and to make uncertainty obvious when it is not.

JSON Semantic Diff is still in alpha, and real-world payloads will expose cases that clean examples do not. If you have an array that it matches incorrectly, or one it refuses to match when it should, I would especially like to see the smallest reproducible example.

Try JSON Semantic Diff

The project is open source on GitHub.