JSON Merge Patch
obsoletes
- rfc-7386 — JSON Merge Patch
Extracted elements (15)
It is not possible to patch part of a target that is not an object, such as replacing just some values in an array. Arrays are replaced wholesale rather than merged element-by-element, which is an intentional scope limitation.
Merge patch documents are suitable only for JSON documents that primarily use objects for their structure and do not make use of explicit null values, because null is overloaded to mean 'delete this key' rather than the JSON null literal.
If the target implementation allows multiple name/value pairs with the same key name, the result of the MergePatch operation on such objects is not defined by this specification.
The merge patch format is not appropriate for all JSON syntaxes. It cannot express setting a member to the JSON null value, nor can it patch arrays partially; alternative patch formats (such as JSON Patch, RFC 6902) should be used in those cases.
If the patch is an object but the target is not an object, the target is set to an empty object before applying the patch's name/value pairs.
If the patch is anything other than a JSON object, the result is to replace the entire target with the entire patch value, regardless of the target's current content.
If the provided merge patch contains members that do not appear within the target, those members are added to the target document.
If the target contains a member that also appears in the merge patch, the target member's value is replaced with the value from the patch.
Null values in the merge patch indicate the removal of existing values in the target. If the patch member's value is null and the name exists in the target, that name/value pair is removed from the target.
The MergePatch operation is defined to operate at the level of data items, not textual representation. It does not preserve whitespace, member ordering, number precision beyond implementation limits, or other textual features.
A JSON merge patch document describes changes to a target JSON document using syntax that mimics the document being modified. Members not in the target are added; existing members have their values replaced; null values signal removal of existing values.
The MergePatch algorithm is a recursive function taking a Target (any JSON value or undefined) and a Patch (any JSON value). If Patch is an Object, it iterates name/value pairs: null values remove target members, non-null values recursively merge. If Patch is not an Object, it returns Patch directly.
IANA registers the MIME media type 'application/merge-patch+json' (type: application, subtype: merge-patch+json) with no required or optional parameters, encoding per RFC 7159, and intended usage COMMON.
All security considerations discussed in Section 5 of RFC 5789 (PATCH Method for HTTP) apply to all uses of the HTTP PATCH method with the application/merge-patch+json media type.
The application/merge-patch+json media type allows user agents to indicate their intention for the server to determine the specific set of change operations to apply to a target resource. It is the server's responsibility to determine the appropriateness of any given change and the user agent's authorization to request such changes.