jsondiff

A comprehensive Python library for computing, applying, and reversing differences between JSON and JSON-like data structures including dictionaries, lists, sets, and tuples. The library provides multiple diff syntaxes to suit different use cases, supports advanced features like path exclusion for ignoring specific JSON paths during comparison, and includes both a Python API and command-line interface for processing JSON and YAML files.

Package Information

• Package Name: jsondiff
• Language: Python
• Installation: pip install jsondiff

Core Imports

import jsondiff
from jsondiff import diff, similarity, JsonDiffer

Import specific symbols for diff structures:

from jsondiff.symbols import delete, insert, add, discard, replace

Basic Usage

import jsondiff as jd
from jsondiff import diff, JsonDiffer
from jsondiff.symbols import delete, insert, add, discard

# Basic dictionary diff
original = {'a': 1, 'b': 2}
modified = {'b': 3, 'c': 4}
diff_result = diff(original, modified)
print(diff_result)  # {'c': 4, 'b': 3, delete: ['a']}

# List diff with insertions
list1 = ['a', 'b', 'c']
list2 = ['a', 'b', 'c', 'd']
diff_result = diff(list1, list2)
print(diff_result)  # {insert: [(3, 'd')]}

# Apply patch using JsonDiffer class
differ = JsonDiffer()
patched = differ.patch(original, diff_result)
print(patched)  # Modified structure

# Set operations
set1 = {'a', 'b', 'c'}
set2 = {'a', 'c', 'd'}
diff_result = diff(set1, set2)
print(diff_result)  # {discard: {'b'}, add: {'d'}}

# Use different syntax for clearer output
diff_result = diff(original, modified, syntax='explicit')
print(diff_result)  # {insert: {'c': 4}, update: {'b': 3}, delete: ['a']}

Architecture

The jsondiff library is built around a flexible architecture:

• Core Functions: High-level diff(), patch(), and similarity() functions providing the main API
• JsonDiffer Class: Central class managing diff computation with configurable options and syntax
• Syntax Classes: Pluggable diff output formats (compact, explicit, symmetric, rightonly)
• Serialization Layer: JSON/YAML loading and dumping with unified interface
• Symbol System: Special symbols representing diff operations (delete, insert, add, etc.)
• CLI Interface: Command-line tool (jdiff) for file-based operations

This design allows for maximum flexibility in how diffs are computed, represented, and applied while supporting various data formats and use cases.

Capabilities

Core Operations

Primary functions for computing differences and measuring similarity between JSON structures. These form the main public API of the library.

def diff(a, b, fp=None, cls=JsonDiffer, **kwargs): ...
def similarity(a, b, cls=JsonDiffer, **kwargs): ...

Core Operations

Diff Syntaxes

Multiple output formats for representing differences, each optimized for different use cases from compact storage to human readability.

class CompactJsonDiffSyntax: ...
class ExplicitJsonDiffSyntax: ...
class SymmetricJsonDiffSyntax: ...
class RightOnlyJsonDiffSyntax: ...

Diff Syntaxes

JsonDiffer Configuration

Main class providing configurable diff computation with options for syntax, serialization, marshaling, and path exclusion.

class JsonDiffer:
    def __init__(self, syntax='compact', load=False, dump=False, marshal=False, ...): ...
    def diff(self, a, b, fp=None, exclude_paths=None): ...
    def patch(self, a, d, fp=None): ...
    def unpatch(self, b, d, fp=None): ...

JsonDiffer Configuration

Serialization

JSON and YAML loading, dumping, and unified serialization interface supporting both string and file operations.

class JsonLoader: ...
class JsonDumper: ...
class YamlLoader: ...
class YamlDumper: ...
class Serializer: ...

Serialization

Command Line Interface

File-based diff operations with support for multiple input formats and syntax options.

jdiff file1.json file2.json -s explicit -f json

Command Line Interface

Symbol System

Special symbols used in diff structures to represent different types of changes:

# Import symbols for working with diff results
from jsondiff.symbols import delete, insert, add, discard, replace, update

# Symbol class
class Symbol:
    def __init__(self, label): ...
    @property
    def label(self): ...

• delete: Keys or indices where elements were removed
• insert: Positions where elements were added (lists)
• add: Elements added to sets
• discard: Elements removed from sets
• replace: Complete replacement of values
• update: Modified values (explicit syntax)

Types

# Available diff syntaxes (accessible via string names in JsonDiffer)
syntax_names = ['compact', 'symmetric', 'explicit', 'rightonly']

# Example: Use syntax names with JsonDiffer
differ = JsonDiffer(syntax='explicit')