Why JSON Patch Beats JSON Merge Patch for Complex Kubernetes Updates

Overview

PATCH is an HTTP method that has gained attention for updating resources. Kubernetes supports both JSON MERGE PATCH and MERGE PATCH, but the author recommends using JSON PATCH because the Merge Patch format is too simple for complex use cases.

JSON PATCH

JSON Patch (RFC 6902) resembles a database transaction. It is a JSON document composed of a sequence of operations such as ADD, REMOVE, REPLACE, MOVE, and COPY.

Example source document:

{
	"users" : [
		{ "name" : "Alice" , "email" : "[email protected]" },
		{ "name" : "Bob" , "email" : "[email protected]" }
	]
}

Patch that replaces Alice’s email and adds a new user:

[
	{ "op" : "replace" , "path" : "/users/0/email" , "value" : "[email protected]" },
	{ "op" : "add" , "path" : "/users/-" , "value" : {
		"name" : "Christine",
		"email" : "[email protected]"
	}}
]

Resulting document:

{
	"users" : [
		{ "name" : "Alice" , "email" : "[email protected]" },
		{ "name" : "Bob" , "email" : "[email protected]" },
		{ "name" : "Christine" , "email" : "[email protected]" }
	]
}

Basic elements of a JSON Patch operation: op indicates the operation type.

Other fields describe the operation’s parameters. path points to the target location in the JSON document and must exist.

The test operation can be used for assertions; if the test evaluates to false, the patch execution is aborted.

JSON MERGE PATCH

JSON Merge Patch (RFC 7396) describes a diff‑style document that contains only the nodes that should change after the patch is applied.

Original JSON:

{
	"a" : "b",
	"c" : {
		"d" : "e",
		"f" : "g"
	}
}

Merge Patch to change a to z and delete c.f:

{
	"a" : "z",
	"c" : {
		"f" : null
	}
}

Result: the value of a becomes z and the key c is removed.

Limitations of JSON Merge Patch:

Deletion is performed by setting a key’s value to null, which makes it impossible to explicitly set a null value.

Arrays cannot be patched; adding or modifying an array element requires sending the entire array.

Merge Patch never produces an error; any malformed patch is silently ignored, which can be unsafe because validation must be performed after the patch, and current implementations cannot roll back on schema validation failures.

Conclusion

JSON Merge Patch is a very simple format with limited applicability. For more complex scenarios, especially when using Kubernetes PATCH, the author advises using JSON PATCH, which supports atomic execution, pre‑ and post‑test checks, and works with any JSON document.

References

https://jsonpatch.com/