JSON Patch

In a previous article, I presented JSON Merge Patch. JSON Patch is simply an alternative!

It is a format that allows to manage the partial modification of JSON document. It is used in REST APIs, via the HTTP PATCH method. Its mime type (Media Type) is application/json-patch+json

JSON Patch Format

A patch JSON document is simply a JSON file containing an array of patch operations.

Here is a small example to get an idea of this format:

[
	{ "op": "add", "path": "/hobbies/1", "value": "Sport" },
	{ "op": "remove", "path": "/job" }
]

In this example, there are two operations:

• An addition of Sport value.
• Deleting the job value

Les opérations

List of operations:

• add: Adds an attribute to an object or adds an element to an array.
  For arrays:
  • The element is inserted before the specified index.
  • The “–” character inserts a value at the end of the array.
• remove: Removes a value.
• replace: Replaces a value.
• move: Moves a value.
• copy: Copies a value.
• test: Verifies that a value is well defined. Otherwise the update fails.

JSON Pointer

This format can be found in the “path” attribute of the operations.

The JSON pointer (IETF RFC 6901) is used to identify a specific value in a JSON document.

This is similar to JSONPath except that it allows you to search and return multiple values.

This format is quite simple:

Take as an example the resource /persons/cyril

• The path starts with a slash
  
• Each segment is separated by a slash
  
• Each segment is either the name of an attribute (for objects) or an index (for arrays)

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "chanel"
		}
	]
}

The name attribute has path /pets/0/name.

Some examples

Add attribute

Let’s add an eye attribute to our resource resource /people/cyril:

[
	{ "op": "add", "path": "/eye", "value": "Green" }
]

The result:

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Add an element to an array

Now let’s add a pet:

[
	{ "op": "add", "path": "/pets/0", "value": {"type": "cat", "name": "Horu"} }
]

The result:

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "Horu"
		}
,
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Modify a value

We are going to change the job:

[
	{ "op": "add", "path": "/job", "value": "Project Manager" }
]

The result:

{
	"firstname": "Cyril",
	"job": "Project Manager",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "Horu"
		}
,
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Null value

There is no special case for the null value, it is possible to assign this value to an attribute.

We will set the job attribute to null:

[
	{ "op": "add", "path": "/job", "value": null }
]

The result:

{
	"firstname": "Cyril",
	"job": null,
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "Horu"
		}
,
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Limitations / Disadvantages

Unlike JSON Merge Patch, this format has no functional limitation. This format allows you to set null values, delete nodes, update tables, etc.

On the other hand, I still find a disadvantage to this format: it is not very readable as soon as there are a certain number of operations.

At first glance, it can be difficult to see what is being updated (unlike JSON Merge Patch).

Conclusion

JSON Patch is a powerful tool for making partial updates to JSON documents. By providing a standardized way of specifying changes to be made to a JSON document, JSON Patch allows for efficient and flexible updates.

From my point of view, JSON Patch stands out from JSON Merge Patch, because the latter is too functionally limited.

Learn more: JSON Patch

Visit our JSON Patch generator to do some tests.