JSON Diff and Patch

TerminusDB
Home Glossary Release History Roadmap
Search…
TerminusX and TerminusDB Technical Documentation
JSON Diff and Patch
JSON Diff and Patch Demonstration
TerminusX
TerminusDB
TerminusX and DB
JSON Diff and Patch
Introduction to TerminusDB JSON Diff and Patch with examples of the available operations using TerminusDB JavaScript and Python clients, and curl.
Key topics
​Use public JSON Diff and Patch directly​
​Use JSON Diff and Patch with a TerminusDB client​
​JSON Diff and Patch operations​
​JSON Diff and Patch examples using curl​
The uses of JSON Diff and Patch
JSON objects are a common way of representing data for software development. The serialization of JSON is simple and facilitates communication via networks and storage in databases. Almost all modern programming languages support JSON objects natively.
When objects are modified in distributed systems, it is useful to compare versions of an object to see what has changed. This is where diff and patch come in.
Diff
A diff takes two JSON objects and presents any differences between them. Diff has several uses. A key use is displaying a clear summary of differences between large objects, enhancing the visibility of changes. This enables manual, user-interface assisted, or client actions to resolve differences. Actions include:
Retain the original object.
Change to the new (or latest) version of the object.
Create a new version of the object.
Patch
A patch applies a diff to two objects to obtain a new object with any differences highlighted. A patch is applied individually or in bulk to a patch endpoint that will apply the patch to the specified data product.
Use public JSON Diff and Patch directly
Use our public endpoints for each operation:
JSON Diff - https://cloud.terminusdb.com/jsondiff
JSON Patch - https://cloud.terminusdb.com/jsonpatch
See Diff and Patch Endpoints for more information, and examples of diff and patch using curl.
Use JSON Diff and Patch with a TerminusDB client
Use JSON Diff and Patch with a TerminusDB JavaScript or Python client to find and handle changes in TerminusDB schemas and documents, JSON schemas, and other document databases such as MongoDB. See [JSON Diff and Patch client tutorials](json-diff-and-patch.md#JSON Diff and Patch-client-tutorials) for use cases, including connectivity with MongoDB.
Requirements
Install a JavaScript or Python TerminusDB client.
Get started
Get started with the simple steps below.
If using TerminusX with Python, connect to your TerminusX cloud instance first - see Connect with WOQLClient for instructions if required.
1. Create an endpoint​
2. Apply a diff to obtain a patch​
3. Review the patch​
4. Apply the patch​
Create an endpoint
Create a client endpoint with WOQLClient.
JavaScript
Python
1
const TerminusClient = require("@terminusdb/terminusdb-client");
2
​
3
var client = new TerminusClient.WOQLClient("http://127.0.0.1:6363")
Copied!
1
from terminusdb_client import WOQLClient
2
​
3
client = WOQLClient("http://localhost:6363/")
Copied!
Apply a diff to obtain a patch
Get the difference/s between two hypothetical documents - Doc1 and Doc2.
JavaScript
Python
Use getDiff
1
let result_patch = await client.getDiff(Doc1, Doc2)
Copied!
Usediff
1
result_patch = client.diff(Doc1, Doc2)
Copied!
Review the patch
Print the contents of a patch.
JavaScript
Python
1
console.log(result_patch)
Copied!
Example usespprint (from pprint import pprint)
1
pprint(result_patch.content)
Copied!
Apply the patch
Apply the patch to Doc1.
JavaScript
Python
1
let after_patch = await client.patch(Doc1, result_patch);
Copied!
1
after_patch = client.patch(Doc1, result_patch)
Copied!
JSON Diff and Patch operations
The available JSON Diff and Patch operations with some examples using curl.
Diff can take the paramters keep which specifies a document describing which fields must be copied in the final object, and a copy_value boolean flag, which specifies whether to specify the exact value in a copy operation.
Copy Diff
Copy is implicit. All properties which are not specifically mentioned will be considered part of an implicit copy. This will make patches more compressed and easier to specify by hand.
Mandatory Diff
@before/@after instructions contain objects specified as tightly as required to obtain ids, or as ids.
1
{ '@id' : "Person/jim",
2
  'date_of_birth' : { '@op' : 'SwapValue',
3
                      '@before' : "1928-03-05",
4
                      '@after' : "1938-03-05"
5
                    }}
Copied!
Optional Diff
Optional diffs also contain @before/@after designations, but potentially null fields to describe missing elements.
1
{ '@id' : "Object/my_object",
2
  'name' : { '@op' : 'SwapValue',
3
             '@before' : null,
4
             '@after' : "Jim" }}
Copied!
Set Diff / Cardinality Diff
Set requires the ability to explicitly remove or add elements - we can do this by maintaining a @before/@after with a list of those which exist only on the left, and only on the right.
List Diff
The list diff requires swaps at a position. We use, @copy, @swap and @keep.
Copy List
Copy the previous list from From_Position to To_Position.
1
{ "@op" : "CopyList",
2
  "@to" : To_Position,
3
  "@rest" : Diff }
Copied!
Swap List
Swap out the list starting from the current point from Previous to Next. This can be used to extend, or drop elements as well as do full replacement.
1
{ "@op" : "SwapList",
2
  "@before" : Previous,
3
  "@after" : Next,
4
  "@rest" : Diff }
Copied!
Patch List
Patch the list starting from the current point with the patch list in "@patch". The patch must be less than or equal to the length of the list.
1
{ "@op" : "PatchList",
2
  "@patch" : Patch,
3
  "@rest" : Diff }
Copied!
Example:
1
var Patch =
2
{ '@id' : "TaskList/my_tasks",
3
  'tasks' : { '@op' : "CopyList",                      % Replace List
4
              '@to' : 2,
5
              '@rest' : { '@op' : "PatchList",
6
                          '@patch' : [{ '@op' : "SwapValue",
7
                                        '@before' : "Task/shopping",
8
                                        '@after' : "Task/climbing"},
9
                                      { '@op' : "SwapValue",
10
                                        '@before' : "Task/cleaning",
11
                                        '@after' : "Task/dining"},
12
                                      { '@op' : "SwapValue",
13
                                        '@before' : "Task/fishing",
14
                                        '@after' : "Task/travelling"}],
15
                          '@rest' : { '@op' : "KeepList" } } }}
16
var Before =
17
{ '@id' : "TaskList/my_tasks",
18
  'tasks' : ["Task/driving", "Task/reading", "Task/shopping",
19
             "Task/cleaning","Task/fishing", "Task/arguing"] }
20
var After =
21
{ '@id' : "TaskList/my_tasks",
22
  'tasks' : ["Task/driving", "Task/reading", "Task/climbing",
23
             "Task/dining", "Task/travelling", "Task/arguing"] }
Copied!
Array Diff
Arrays will allow index swapping or "shrink" and "grow".
Force Diff
A "Force Diff" will set the value of a location regardless of the current read-state. This is a potentially unsafe operation as there is no guarantee we are seeing the object state version we think we are.
1
{ '@id' : "Employee/012" ,
2
  'name' : { '@op' : 'ForceValue',
3
             '@after' : "Jake" }}
Copied!
Table Diff
A Table diff specifies the differences and similarities between the two tables. These tables need not have the same dimensions. In order to describe these differences, we use a ModifyTable patch. The ModifyTable patch is comprised of copies, deletes, inserts and moves.
copies give the sections of the table which can be copied verbatim. deletes gives all segments which are to be removed from the original. inserts gives all segments which are to be inserted into the new table.
moves specifies segments that are the same in both tables, but have moved location. This is particularly useful as moving rows and columns is a typical operation in a table (such as a CSV or Excel document).
Example Table
Given the following table:
1
[['Job Title','Company','Location','Company Size','Company Industry'],
2
 ['Sr. Mgt.','Boeing','USA','Large','Aerospace'],
3
 ['Data Architect','Airbus','France','Large','Aerospace'],
4
 ['Founder','Ellie Tech','Sweden','Startup','AI'],
5
 ['Platform Engineer','Adidas','Germany','Large','Apparel']]
Copied!
And a sorted version of the same (sorting on the first column):
1
[['Job Title','Company','Location','Company Size','Company Industry'],
2
 ['Data Architect','Airbus','France','Large','Aerospace'],
3
 ['Founder','Ellie Tech','Sweden','Startup','AI'],
4
 ['Platform Engineer','Adidas','Germany','Large','Apparel'],
5
 ['Sr. Mgt.','Boeing','USA','Large','Aerospace']]
Copied!
We have the following patch resulting from the diff:
1
{'@op':"ModifyTable",
2
 dimensions:{'@after':[5,5],'@before':[5,5]},
3
 deletes:[],
4
 inserts:[],
5
 copies:[{'@at':{'@height':1,'@width':5,'@x':0,'@y':0},'@value':[['Job Title','Company','Location','Company Size','Company Industry']]}],
6
 moves:[{'@from':{'@height':1,'@width':5,'@x':0,'@y':1},
7
         '@to':{'@height':1,'@width':5,'@x':0,'@y':4},
8
         '@value':[['Sr. Mgt.','Boeing','USA','Large','Aerospace']]},
9
        {'@from':{'@height':1,'@width':5,'@x':0,'@y':2},
10
         '@to':{'@height':1,'@width':5,'@x':0,'@y':1},
11
         '@value':[['Data Architect','Airbus','France','Large','Aerospace']]},
12
        {'@from':{'@height':1,'@width':5,'@x':0,'@y':3},
13
         '@to':{'@height':1,'@width':5,'@x':0,'@y':2},
14
         '@value':[['Founder','Ellie Tech','Sweden','Startup','AI']]},
15
        {'@from':{'@height':1,'@width':5,'@x':0,'@y':4},
16
         '@to':{'@height':1,'@width':5,'@x':0,'@y':3},
17
         '@value':[['Platform Engineer','Adidas','Germany','Large','Apparel']]}]}
Copied!
Diff and Patch Endpoints
The Patch and Diff endpoints expose endpoints to obtain diffs or patches of data. Use our public endpoint for each operation:
JSON Diff - https://cloud.terminusdb.com/jsondiff
JSON Patch - https://cloud.terminusdb.com/jsonpatch
Diff
The diff endpoint takes a POST of two JSON documents, before, and after. This endpoint then returns a 200 and a patch which takes before to after if applied using the patch interface.
The payload is structured as a JSON document with one of the following forms:
With "before" and "after", pointing to the documents you would like to diff.
With "before_data_version", "after" and "document_id", specifying the data version or commit ID with which to compare the given after document.
With "before_data_version", "after_data_version" and "document_id" specifying the data version or commit ID with which to compare the document given by "document_id"
With "before_data_version", "after_data_version", meaning that we would like to get a diff for all documents between the two specified data versions.
There are also two options:
keep: A dictionary which has keys which need to be copied
copy_value: Which specifies that we should make explicit which values existed during a list copy.
An example of the payload:
1
{ "before" : { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"},
2
  "after" :  { "@id" : "Person/Jane", "@type" : "Person", "name" : "Janine"}}
Copied!
Which would result in the following patch:
1
{ "name" : { "@op" : "SwapValue", "@before" : "Jane", "@after": "Janine" }}
Copied!
An example of a payload comparing commits or dataversions:
1
{ "before_data_version" : "branch:s7dde27gyj8ezat3itw5nr3peu1lymh"
2
  "document_id" : "terminusdb:///data/test/665df8a9c3a58be6db622be4b37a76bea46c3e5e3cd2db923e708e574d1566be",
3
  "after" :  { "@id" : "Person/Jane", "@type" : "Person", "name" : "Janine"}}
Copied!
An example of a payload comparing only dataversions:
1
{ "before_data_version" : "branch:s7dde27gyj8ezat3itw5nr3peu1lymh"
2
  "after_data_version" : "branch:jb81rgx9lzow35r3pkrsvdf5l75kaq"
3
  "document_id" : "terminusdb:///data/test/665df8a9c3a58be6db622be4b37a76bea46c3e5e3cd2db923e708e574d1566be"}
Copied!
Diff examples using curl
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsondiff' -d \
2
  '{ "before" : { "asdf" : "foo", "fdsa" : "bar"}, "after" : { "asdf" : "bar", "fdsa" : "bar"}, "keep" : { "fdsa" : true}}'
3
# Output: {
4
  "asdf": {"@after":"bar", "@before":"foo", "@op":"SwapValue"},
5
  "fdsa":"bar"
6
}
Copied!
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsondiff' -d \
2
  '{ "before" : [{ "asdf" : "foo"}], "after" : [{ "asdf" : "bar"}]}'
3
# Output: [ {"asdf": {"@after":"bar", "@before":"foo", "@op":"SwapValue"}} ]
Copied!
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsondiff' -d \
2
  '{ "before" : [0,1,2], "after" : [0,1,2,3]}'
3
​
4
# Output:
5
{
6
  "@op":"CopyList",
7
  "@rest": {
8
    "@after": [3 ],
9
    "@before": [],
10
    "@op":"SwapList",
11
    "@rest": {"@op":"KeepList"}
12
  },
13
  "@to":3
14
}
Copied!
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsondiff' -d \
2
  '{ "before" : [0,1,2], "after" : [0,1,2,3], "copy_value" : true}'
3
​
4
# Output:
5
{
6
  "@op":"CopyList",
7
  "@rest": {
8
    "@after": [3 ],
9
    "@before": [],
10
    "@op":"SwapList",
11
    "@rest": {"@op":"KeepList", "@value": []}
12
  },
13
  "@to":3,
14
  "@value": [0, 1, 2 ]
15
}
Copied!
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsondiff' -d \
2
  '{ "before" : { "asdf" : { "fdsa" : "quux"}}, "after" : { "asdf" : { "fdsa" : "quuz" }}}'
3
​
4
# Output:
5
{
6
  "asdf": {"fdsa": {"@after":"quuz", "@before":"quux", "@op":"SwapValue"}}
7
}
Copied!
Patch
Patch takes a POST with a before document and a patch and produces an after document.
1
{ "before" : { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"}
2
  "patch" : {"name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }}}
Copied!
Resulting in the following document:
1
{ "@id" : "Person/Jane", "@type" : "Person", "name" : "Janine"}
Copied!
Patch examples using curl
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsonpatch' -d \
2
   '{ "before" : { "alpha" : 1, "asdf" : { "fdsa" : "quux"}}, "patch" : {
3
      "asdf": {"fdsa": {"@after":"quuz", "@before":"quux", "@op":"SwapValue"}}
4
}}'
5
# Output: {"alpha":1, "asdf": {"fdsa":"quuz"}}
Copied!
1
$ curl -X POST -H "Content-Type: application/json" 'https://cloud.terminusdb.com/jsonpatch' -d '
2
{ "before" : [0,1,2], "patch" : {
3
  "@op":"CopyList",
4
  "@rest": {
5
    "@after": [3 ],
6
    "@before": [],
7
    "@op":"SwapList",
8
    "@rest": {"@op":"KeepList"}
9
  },
10
  "@to":3
11
}}'
12
#Output: [0, 1, 2, 3 ]
Copied!
See Also
JSON Diff and Patch demonstration
A demonstration of using JSON Diff and Patch with a TerminusDB or TerminusX client, including the use of JSON Diff and Patch with MongoDB.
JSON Diff and Patch client functions
JavaScript client diff and patch.
Python client diff and patch.
TerminusX and TerminusDB Technical Documentation
JSON Diff and Patch Demonstration
Last modified 2d ago