JSON Merge Patch

JSON merge patch uses a syntax that closely mimics the document being modified. Recipients determine changes by comparing the patch against the current target: missing members are added, existing members are replaced, and null signals deletion. This makes patches human-readable without a separate diff language.

json, http

MergePatch operates at the level of data items, not textual representation. The operation is not required to preserve whitespace, member ordering, or number precision beyond the target implementation's capabilities. This simplifies implementation by decoupling patch semantics from serialization details.

json

Null values in a merge patch are overloaded to mean 'remove this member' rather than 'set this member to null'. As a consequence, the format is unsuitable for JSON documents that legitimately use explicit null values, because there is no way to distinguish a deletion instruction from a real null.

json

The format is intentionally limited to object-structured JSON documents. It cannot selectively patch elements within arrays; an array can only be replaced wholesale. This constraint is acknowledged in the spec as a known limitation of the design.

json

If the target implementation allows multiple name/value pairs with the same key (duplicate keys, which RFC 7159 permits but discourages), the result of MergePatch on such objects is explicitly undefined by this specification.

json

It is not possible to use merge patch to modify only part of a non-object value, such as replacing individual elements within an array. Any patch targeting an array position must replace the entire array.

json

For each Name/Value pair in the patch where Value is null and the Name exists in the Target, the Name/Value pair MUST be removed from Target. If the Name does not exist in Target, the null entry is silently ignored.

json

If the Patch is an Object but the Target is not an Object, the Target MUST be set to an empty Object before iterating the patch members. The prior non-object content of Target is discarded.

json

If the Patch is anything other than an Object, the result MUST be to replace the entire Target with the entire Patch. There is no partial application when the patch is a scalar, array, or null.

json

Resources using the 'application/merge-patch+json' media type are required to conform to the 'application/json' media type and are subject to the encoding considerations in RFC 7159 Section 8.

json, http, registry

The MergePatch(Target, Patch) algorithm is the normative processing core: if Patch is an Object, iterate its Name/Value pairs — null values remove the named member from Target, non-null values recursively MergePatch into Target[Name]; if Patch is not an Object, return Patch (wholesale replacement).

json

IANA registers the MIME media type 'application/merge-patch+json' (type: application, subtype: merge-patch+json). No required or optional parameters; encoding follows application/json (RFC 7159); change controller is IESG.

registry, json, http

All security considerations from RFC 5789 (HTTP PATCH method) apply to every use of HTTP PATCH with the 'application/merge-patch+json' media type, including risks around partial updates and concurrent modification.

security, http

The 'application/merge-patch+json' media type lets a user agent instruct a server to determine and apply a specific set of changes. It is the server's responsibility to verify both the appropriateness of the requested changes and the user agent's authorization to make them. The specification does not define how to perform these checks.

security, http