Why JSON Array Diffing Is Harder Than It Looks

JSON array differencing presents challenges that extend beyond simply changing a field and reordering the surrounding array. Many JSON diff tools compare arrays by position, which works well for arrays whose order carries meaning. However, when an array represents a collection of records, positional matching can lead to a significant amount of noise.

Consider two JSON payloads: the original and the changed version. The original contains three users with distinct user IDs, names, roles, and statuses. The changed payload includes the same users but with altered order and statuses. A positional comparison method would pair the first object on the left with the first object on the right, the second with the second, and so on. This approach can incorrectly report that several unchanged users have been modified simply because their positions have changed.

The real challenge lies in identifying corresponding records before comparing their fields. JSON Semantic Diff attempts to solve this by trying to identify corresponding records before comparing their fields. The key issue is determining which object on the left corresponds to which on the right. While it may be tempting to look for a field named "id" for this purpose, real payloads rarely make it that simple.

Identity fields can have various names, such as "id," "userId," "orderNumber," "sku," "email," or even something specific to the domain. Sometimes, no single field is enough for identification, and a combination of fields may be required.

To infer identity from the data, JSON Semantic Diff evaluates individual fields and field combinations as potential identities. It uses several signals to score each candidate identity. These signals include uniqueness, match coverage, population overlap, completeness, type consistency, and name hint. By combining these signals and applying a small complexity penalty for composite candidates, the system selects the most reliable identity.

In this case, the selected identity scored 94%, outperforming the second candidate by a 14.3-point margin.

However, automatic matching must also pass safety gates to ensure that the selected identity is unique, covers a significant portion of both arrays, and has a margin over the second-best candidate. If two identities receive nearly identical scores, the matcher must choose the most appropriate one to avoid making incorrect pairings.

In some cases, composite identities may be necessary, particularly for inventory data. For example, inventory records might have attributes like "store," "category," "productID," and "quantity." By considering multiple fields and their combinations, JSON Semantic Diff aims to accurately identify corresponding records and minimize noise in the diffing process.