JSON, the go-to format for APIs and many other things, is hard to avoid. But when it comes to modifying an existing JSON document, a question arises: should you send an entire document with the new values, or simply describe the changes to be made?
There are actually two standards designed to address this need: JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902).
Both allow you to modify JSON documents without having to systematically send all the data. However, their behavior is quite different in practice. I'll go over their specific features, with a few concrete examples, to show when I would choose one over the other.
JSON Merge Patch: Modifying a document with a JSON object
Let's start with JSON Merge Patch, defined in RFC 7396. Its principle is quite simple: you send a JSON object containing only the properties you want to modify. The server then merges this object with the existing document.
Let's take the following JSON document representing a user:
{
"id": 42,
"name": "John",
"email": "john@example.com",
"active": true,
"address": {
"city": "Paris",
"country": "France"
}
}
Let's say I only want to change the user's email address and status. With JSON Merge Patch, I can send:
{
"email": "john.doe@example.com",
"active": false
}
The server then applies these changes to the existing document. Properties that are not mentioned remain unchanged. The result is as follows:
{
"id": 42,
"name": "John",
"email": "john.doe@example.com",
"active": false,
"address": {
"city": "Paris",
"country": "France"
}
}
This is really convenient for REST APIs. Rather than sending all the information about a user, I can send only the fields affected by the change.
Modifying a nested property
JSON Merge Patch also works with nested objects.
For example, to change only the user's city:
{
"address": {
"city": "Lyon"
}
}
The country property is preserved. Merging is therefore recursive when dealing with JSON objects. However, be careful: if an existing property contains an object and the patch provides a value that is not an object, such as an array, for example, the old value is replaced entirely!
Removing a property with null
There is an important detail in JSON Merge Patch: a property associated with the null value is removed from the target document!
For example:
{
"email": null
}
After applying the patch, the email property no longer exists. This is something to be aware of, because it makes it impossible to distinguish between two intentions in a straightforward way:
- Explicitly assigning the
nullvalue to a property. - Removing that property.
With JSON Merge Patch, these two operations are not equivalent: null is used to request deletion.
What about arrays?
Arrays are another particular feature of JSON Merge Patch.
Unlike objects, they are not merged element by element. An array provided in the patch completely replaces the existing array.
Let's imagine this document:
{
"tags": ["php", "javascript", "python"]
}
With this patch:
{
"tags": ["php", "typescript"]
}
The result will be:
{
"tags": ["php", "typescript"]
}
It is therefore not possible to directly request the addition of a single element to an array. You have to send the entire new array.
JSON Patch: Describing the exact operations to perform
JSON Patch, defined in RFC 6902, takes a completely different approach. Instead of sending an object containing the new values, you send a list of operations to execute on the JSON document.
Each operation specifies, among other things:
- The operation type (
op). - The path of the property concerned (
path). - The value to use, when required by the operation (
value).
Let's go back to our user example. To change the email address and status, I can send the following patch:
[
{
"op": "replace",
"path": "/email",
"value": "john.doe@example.com"
},
{
"op": "replace",
"path": "/active",
"value": false
}
]
The final document will be identical to the one obtained with JSON Merge Patch.
The difference lies in how the changes are described: here, each change is explicit and independent.
In my personal opinion, this format is not very readable once you start modifying a large number of fields.
The main available operations
JSON Patch defines six different operations.
| Operation | Description |
|---|---|
add | Adds a property or an element |
remove | Removes a property or an element |
replace | Replaces an existing value |
move | Moves a value |
copy | Copies a value |
test | Checks whether a value matches the expected one |
This provides more possibilities than JSON Merge Patch.
Adding a property
To add a new property to our user, I use the add operation:
[
{
"op": "add",
"path": "/phone",
"value": "+33123456789"
}
]
If the property does not exist, it is created. If it already exists, its value is replaced.
Removing a property
To remove the email address, simply use remove:
[
{
"op": "remove",
"path": "/email"
}
]
Unlike JSON Merge Patch, deletion is explicit here. I can therefore perfectly well assign the value null to a property without requesting its removal:
[
{
"op": "replace",
"path": "/email",
"value": null
}
]
This is an important difference between the two standards.
Adding an element to an array
This is probably one of the most interesting advantages of JSON Patch.
Let's go back to our tags array:
{
"tags": ["php", "javascript", "python"]
}
To add an element to the end of the array, I can use add with the /tags/- path:
[
{
"op": "add",
"path": "/tags/-",
"value": "typescript"
}
]
The result will be:
{
"tags": ["php", "javascript", "python", "typescript"]
}
It is also possible to insert an element at a specific position. For example, /tags/1 inserts a value at index 1 without replacing the element already there.
Moving and copying values
JSON Patch also allows you to move or copy properties using the move and copy operations.
These operations use an additional parameter: from, which indicates the path of the source value.
For example, to move the city from the address to a new location property:
[
{
"op": "move",
"from": "/address/city",
"path": "/location"
}
]
The city property is then removed from address, and its value is assigned to location.
With copy, the source property remains in the document.
Checking a value before modifying the document
The test operation is also interesting, particularly when I want to avoid applying changes if the document does not match the expected state.
For example:
[
{
"op": "test",
"path": "/active",
"value": true
},
{
"op": "replace",
"path": "/active",
"value": false
}
]
The first operation checks that active is indeed set to true. If it isn't, applying the patch fails.
JSON Patch operations are applied in order. If one of them fails, the entire sequence must not be applied to the target document.
JSON Pointer: How do you identify a property?
You may have noticed the paths used in the previous examples: /email, /address/city, or even /tags/1.
They follow a syntax defined by another standard: JSON Pointer (RFC 6901).
JSON Pointer allows you to precisely identify a value in a JSON document using a path.
A few examples:
| JSON Pointer | Targeted value |
|---|---|
/name | The name property |
/address/city | The city property inside address |
/tags/0 | The first element of the tags array |
/users/2/email | The email address of the third user |
There are also two characters that require special handling in property names:
~is represented by~0./is represented by~1.
For example, to target a property named first/name, the path will be /first~1name.
This syntax is used by JSON Patch to identify the properties to modify.
JSON Merge Patch vs JSON Patch: Which one should you choose?
Now that we've looked at both approaches, which one should you choose when developing an API?
It all depends on the nature of the changes you need to make.
| Criterion | JSON Merge Patch | JSON Patch |
|---|---|---|
| Standard | RFC 7396 | RFC 6902 |
| Format | JSON object | Array of operations |
| Modify a property | Yes | Yes |
| Remove a property | With null | With remove |
Explicitly assign null | No, not directly | Yes |
| Modify an array element | No, full replacement | Yes |
| Move a property | No | Yes |
| Copy a property | No | Yes |
| Check a value | No | Yes, with test |
For simple changes, I find JSON Merge Patch particularly pleasant to use. Its syntax is close to that of a regular JSON object, and it is easy to understand, even without knowing the standard.
On the other hand, when changes become more specific, JSON Patch has the advantage. It allows you to manipulate individual array elements, move properties, or check certain values before proceeding.
In a REST API, both can be used with the HTTP PATCH method, but they use different MIME types:
- JSON Merge Patch:
application/merge-patch+json - JSON Patch:
application/json-patch+json
It is therefore important for the server to know which patch format it is receiving.
Conclusion
JSON Merge Patch and JSON Patch ultimately address the same need: modifying a JSON document without having to systematically send its entire contents.
The first prioritizes simplicity through the merging of JSON objects. The second offers a more precise approach, based on a sequence of explicit operations.
That said, some implementations still do things differently. This is the case, for example, with certain JSON Merge Patch implementations that adopt different behavior for the null value. Not always easy to make sense of it all!
By the way, Jsoning offers tools related to JSON Patch: JSON Patch Generator. You can compare two JSON documents and generate the operations needed to go from one to the other 🙂