Introduction to JSON Merge Patch

{JSON Merge Patch}

Table of Contents

What is it? What is it used for?

JSON Merge Patch is a data format that allows describing modifications to be made to a JSON document.

This format can be used in REST APIs to handle partial modifications of resources via the HTTP PATCH method.

The JSON Merge Patch format is itself a JSON document! In short, this JSON only contains the modifications to be made.

The interest of JSON Merge Patch

When updating a resource in a REST API, we typically use the PUT method.

The PUT method updates the entire resource, which can pose several issues:

We need to have the entire resource to update it.
When the resource is large, updating it can quickly become resource-intensive.

This is where the PATCH method and the use of JSON Merge Patch come in. They provide the ability to partially update a resource!

And concretely?

Modifying an attribute

Let’s take the example of the resource /people/cyril

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"]
}

If we want to change the job of this person, with the PUT method, we need to completely send back the resource:

{
	"firstname": "Cyril",
	"job": "
Project Manager",
	"hobbies": ["Cooking"]
}

Now with JSON Merge Patch, we only send what needs to be updated:

{
	"job": "Project Manager"
}

And voila, this format is quite simple and intuitive!

Add an attribute

Now, if we want to add an attribute, we just need to add it:

{
	"birthday": "1982-10-14"
}

We get the following result:

{
	"firstname": "Cyril",
	"job": "
Project Manager",
	"hobbies": ["Cooking"],
	"birthday": "1982-10-14"
}

To delete an attribute

To delete an attribute, simply indicate it with a null value:

{
	"birthday": null
}

The resulting JSON would be:

{
	"firstname": "Cyril",
	"job": "
Project Manager",
	"hobbies": ["Cooking"]
}

REST API

Ce format est donc à utiliser avec la méthode HTTP PATCH.

Son media type est:

application/json+merge-patch

Limitations

JSON Merge Patch is really simple to use, and its learning curve is quick. Unfortunately, this format has several limitations, some of which are quite inconvenient.

“Null value”

As we saw in the “Removing an Attribute” section, the null value is used to remove a node. Therefore, it is impossible to assign the null value!

Functionally, this point may not be very problematic.

Updating an Array

From my point of view, this is the most annoying point with this format. Indeed, arrays cannot be partially updated!

If I want to add a hobby, I have to completely send the array:

{
	"hobbies": ["Cooking", "Running"]
}

The JSON Merge Patch only allows partial updates for objects. Everything that is not an object will be completely replaced.

PHP code snippet to handle JSON Merge Patch

Managing partial updates via JSON Merge Patch is quite simple in PHP. Here is an example code:

function JSONMergePatch($target, $patch) {
	if (is_object($patch)) {
		if (!is_object($target)) {
			$target = new \stdclass();
		}
		foreach($patch as $name => $value) {
			if ($value === null) {
				// When receiving a null value, we delete the corresponding node.
				if (property_exists($target, $name)) {
					unset($target->$name);
				}
			} else {
				if (!isset($target->$name)) {
					$target->$name = null;
				}
				// Recursive call to handle sub-trees
				$target->$name = JSONMergePatch($target->$name, $value);
			}
		}
		return $target;
	} else {
		// This is not an object, we replace the node
		return $patch;
	}
}

JSON Merge Path vs JSON Patch

JSON Merge Patch is not the only format available to handle partial updates in APIs.

One of its competitors is JSON Patch, which is less intuitive but has the advantage of not having the limitations of JSON Merge Patch.

Conclusion

To summarize, JSON Merge Patch is intuitive and easy to implement. However, it is quite limited and loses its relevance when managing arrays.

For more information, see the RFC.