RFC 7396 / START HERE
JSON Merge Patch, before the details
JSON Merge Patch: JSON means JavaScript Object Notation. Merge Patch is the name of a change-document format.
A JSON Merge Patch describes changes using a JSON value shaped like the desired update. An object patch names members to merge, add or remove, while other patch values replace the target.
The idea in one picture
Read the current JSON value
Interpret the merge patch
Produce the changed value
A simplified picture of the idea; the chapters explain the actual mechanisms.
Why it exists
Applications often need to update just a few object members while keeping the others. RFC 7396 defines one common set of merge rules and a media type, so the sender and recipient can agree on what the patch means.
A familiar example
A settings app can send {"color":"green"} to change color while retaining other settings. A null-valued patch member removes a field, and an array replaces the whole array; this format is not suitable for every data model.
Helpful background
You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.
What you’ll learn next
Begin with chapter one, or choose a topic.
- Merge object membersAn object patch visits the members it names, recursively updating nested objects while leaving unmentioned members alone.→
- Remove a member with nullA null value inside an object patch removes that named member rather than assigning null to it.→
- Replace an entire arrayAn array in the patch is a replacement value, not a list of element edits or items to append.→
- Check the patch type firstThe type of the patch decides whether to merge object members or replace the whole target.→
- Identify the format and check permissionThe media type identifies merge semantics, while the server separately decides whether the requested changes are appropriate and authorized.→
This introduction explains RFC 7396 (2014). Read the original RFC ↗