0
# jsondiff
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: jsondiff
7
- **Language**: Python
8
- **Installation**: `pip install jsondiff`
9

10
## Core Imports
11

12
```python
13
import jsondiff
14
from jsondiff import diff, similarity, JsonDiffer
15
```
16

17
Import specific symbols for diff structures:
18

19
```python
20
from jsondiff.symbols import delete, insert, add, discard, replace
21
```
22

23
## Basic Usage
24

25
```python
26
import jsondiff as jd
27
from jsondiff import diff, JsonDiffer
28
from jsondiff.symbols import delete, insert, add, discard
29

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

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

42
# Apply patch using JsonDiffer class
43
differ = JsonDiffer()
44
patched = differ.patch(original, diff_result)
45
print(patched)  # Modified structure
46

47
# Set operations
48
set1 = {'a', 'b', 'c'}
49
set2 = {'a', 'c', 'd'}
50
diff_result = diff(set1, set2)
51
print(diff_result)  # {discard: {'b'}, add: {'d'}}
52

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

58
## Architecture
59

60
The jsondiff library is built around a flexible architecture:
61

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

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

71
## Capabilities
72

73
### Core Operations
74

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

77
```python { .api }
78
def diff(a, b, fp=None, cls=JsonDiffer, **kwargs): ...
79
def similarity(a, b, cls=JsonDiffer, **kwargs): ...
80
```
81

82
[Core Operations](./core-operations.md)
83

84
### Diff Syntaxes
85

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

88
```python { .api }
89
class CompactJsonDiffSyntax: ...
90
class ExplicitJsonDiffSyntax: ...
91
class SymmetricJsonDiffSyntax: ...
92
class RightOnlyJsonDiffSyntax: ...
93
```
94

95
[Diff Syntaxes](./diff-syntaxes.md)
96

97
### JsonDiffer Configuration
98

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

101
```python { .api }
102
class JsonDiffer:
103
    def __init__(self, syntax='compact', load=False, dump=False, marshal=False, ...): ...
104
    def diff(self, a, b, fp=None, exclude_paths=None): ...
105
    def patch(self, a, d, fp=None): ...
106
    def unpatch(self, b, d, fp=None): ...
107
```
108

109
[JsonDiffer Configuration](./jsondiff-class.md)
110

111
### Serialization
112

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

115
```python { .api }
116
class JsonLoader: ...
117
class JsonDumper: ...
118
class YamlLoader: ...
119
class YamlDumper: ...
120
class Serializer: ...
121
```
122

123
[Serialization](./serialization.md)
124

125
### Command Line Interface
126

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

129
```bash
130
jdiff file1.json file2.json -s explicit -f json
131
```
132

133
[Command Line Interface](./cli.md)
134

135
## Symbol System
136

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

139
```python { .api }
140
# Import symbols for working with diff results
141
from jsondiff.symbols import delete, insert, add, discard, replace, update
142

143
# Symbol class
144
class Symbol:
145
    def __init__(self, label): ...
146
    @property
147
    def label(self): ...
148
```
149

150
- `delete`: Keys or indices where elements were removed
151
- `insert`: Positions where elements were added (lists)
152
- `add`: Elements added to sets
153
- `discard`: Elements removed from sets  
154
- `replace`: Complete replacement of values
155
- `update`: Modified values (explicit syntax)
156

157
## Types
158

159
```python { .api }
160
# Available diff syntaxes (accessible via string names in JsonDiffer)
161
syntax_names = ['compact', 'symmetric', 'explicit', 'rightonly']
162

163
# Example: Use syntax names with JsonDiffer
164
differ = JsonDiffer(syntax='explicit')
165
```