JSON-delta

2.0.2 · maintenance · verified Sun Apr 12

JSON-delta is a multi-language software suite for computing deltas between JSON-serialized data structures and applying those deltas as patches. It aims to minimize communications overhead when manipulating data structures between separate programs. The Python implementation, currently at version 2.0.2, is considered the reference implementation, though it has seen limited development activity since its last release in October 2020.

Warnings

gotcha The `json-delta` project has shown limited activity since its last release in October 2020. This indicates that it may not be actively maintained, which could lead to unaddressed bugs, security vulnerabilities, or lack of support for newer Python versions or features.
Fix: Assess the project's long-term viability for your application. Consider contributing to its maintenance or evaluating alternative, more actively maintained JSON diffing libraries if long-term support is critical.
gotcha The diff format generated by `json-delta` is a custom sequence of 'stanzas' (e.g., `[[key_path], update_value]`) and is not directly compatible with standard JSON Patch (RFC 6902). Users expecting an RFC 6902 compliant format will need to implement a conversion layer or choose a different library.
Fix: Familiarize yourself with the `json-delta` specific diff format as documented. If interoperability with RFC 6902 is required, consider using libraries explicitly designed for JSON Patch.
gotcha When `diff` generates a deletion stanza (i.e., a stanza without an `update` value), the `patch` function cannot reconstruct the original deleted content if it's later needed for 'unpatching' or auditing. This means some diffs are not fully reversible without external knowledge of the deleted data.
Fix: If full reversibility (the ability to 'unpatch' to the exact original state) is required, ensure that deleted data is stored or retrieved through other means, or consider a library that explicitly supports reversible diff formats.
gotcha The `diff` function's `minimal` and `verbose` parameters are primarily for backward compatibility and can be superseded by more specific parameters like `array_align`, `compare_lengths`, and `common_key_threshold`. Using `minimal` in conjunction with these specific parameters might lead to unexpected behavior or warnings if `verbose` is also enabled.
Fix: Prefer using the more specific parameters (`array_align`, `compare_lengths`, `common_key_threshold`) directly to control diff behavior, rather than relying on the `minimal` parameter, especially if fine-grained control is needed.

Install

pip install json-delta Install with pip

Imports

diff
```
from json_delta import diff
```
Imports the function to compute the difference between two JSON structures.
patch
```
from json_delta import patch
```
Imports the function to apply a computed diff to a JSON structure.

Quickstart

This quickstart demonstrates how to compute the difference (delta) between two Python dictionaries representing JSON structures and then apply that delta to the original structure to reconstruct the modified one.

from json_delta import diff, patch

# Original JSON-like data structure
a = {
    "name": "John Doe",
    "age": 30,
    "address": {
        "street": "123 Main St",
        "city": "Anytown"
    },
    "hobbies": ["reading", "hiking"]
}

# Modified JSON-like data structure
b = {
    "name": "Jane Doe",
    "age": 31,
    "address": {
        "street": "456 Oak Ave",
        "city": "Otherville"
    },
    "hobbies": ["reading", "coding", "swimming"]
}

# Compute the diff
delta = diff(a, b)
print(f"Computed Delta: {delta}")

# Apply the patch to 'a' to get 'b_reconstructed'
b_reconstructed = patch(a, delta)
print(f"Reconstructed B: {b_reconstructed}")

assert b == b_reconstructed
print("Original 'b' and reconstructed 'b' are equal.")

view raw JSON →