RFC 7386

JSON Merge Patch

📅 published October 2014, from ietf

RFC 7386: JSON Merge Patch 🎀

Okay bestie, here's the paperwork vibe check 📋✨

  • Series: Internet Engineering Task Force (IETF), Request for Comments 7386
  • Authors: Paul Hoffman (VPN Consortium) and James M. Snell 💅
  • Category: Standards Track
  • ISSN: 2070-1721
  • Date: October 2014
  • Obsoletes and updates: the title block doesn't list either one 🦋

Abstract ✨

This spec defines the JSON merge patch format and how to process it. The format is mainly meant for the HTTP PATCH method, as a way to describe a bunch of changes you want to make to a target resource's content 🌸

Status of This Memo 📜

This is an Internet Standards Track document 🔥

It's a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 5741 🧚

Info about the current status of this doc, any errata, and how to give feedback is at http://www.rfc-editor.org/info/rfc7386 💜

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. 🫶

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the date it was published. Please actually read these, because they spell out your rights and restrictions for this document 🙈

Code components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License ⚠️

Table of Contents 🗺️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Processing Merge Patch Documents  . . . . . . . . . . . . . .   3
3.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
5.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
  6.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
  6.2.  Informative References  . . . . . . . . . . . . . . . . .   7
Appendix A.  Example Test Cases . . . . . . . . . . . . . . . . .   8
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   9
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1. Introduction 💖

So this spec defines three things: the JSON merge patch document format, the processing rules, and the MIME media type identifier that goes with it. The format is mainly for the HTTP PATCH method [RFC5789], which lets you describe a set of changes to a target resource's content. It's giving "describe the diff, not the whole thing" 😭

A JSON merge patch document describes the changes you want made to a target JSON document. The syntax looks a LOT like the document you're modifying, which is so iconic 🎀 Recipients figure out the exact changes by comparing the patch to the current content of the target. If the patch has members that aren't in the target, those get added. If the target already has the member, its value gets replaced. And null values are special: they mean "remove this existing value from the target" 🗑️

Here's an example. Say the original JSON document is:

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

If you want to change the value of "a" and remove "f", you send:

PATCH /target HTTP/1.1
Host: example.org
Content-Type: application/merge-patch+json

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

Once that's applied, "a" becomes "z" and "f" is gone, and everything else stays untouched 🧚

Real talk though: merge patch docs are a great fit for JSON that's mostly objects for structure and doesn't use explicit null values. The merge patch format is NOT appropriate for every JSON syntax, so don't force it 🙈

2. Processing Merge Patch Documents 🔥

JSON merge patch documents describe, by example, a set of changes to make to a target resource. Recipients are the ones responsible for comparing the merge patch with the target's current content to work out the specific change operations to apply 💅

To apply a merge patch document to a target resource, the system ends up with the effect of the following function, written as pseudocode. The function is called MergePatch and takes two arguments: the target resource document and the merge patch document. Target can be any JSON value or undefined. Patch can be any JSON value 🌸

define MergePatch(Target, Patch):
  if Patch is an Object:
    if Target is not an Object:
  Target = {} # Ignore the contents and set it to an empty Object
    for each Name/Value pair in Patch:
  if Value is null:
    if Name exists in Target:
      remove the Name/Value pair from Target
  else:
    Target[Name] = MergePatch(Target[Name], Value)
    return Target
  else:
    return Patch

A few things to note about this function. If the patch is anything besides an object, the result is always to replace the whole target with the whole patch. Also, you can't patch just part of a target that isn't an object, like swapping out a few values inside an array 🙅‍♀️

MergePatch works on data items, NOT on the textual representation. Nobody expects it to keep stuff at the text level like white space, member ordering, number precision beyond what the target's implementation supports, and so on 🧠 And even if the target implementation allows multiple name/value pairs with the same name, the result of MergePatch on those objects is undefined. Not defined, bestie 💀

3. Example 🦋

Here's a sample JSON document:

{
  "title": "Goodbye!",
  "author" : {
"givenName" : "John",
"familyName" : "Doe"
  },
  "tags":[ "example", "sample" ],
  "content": "This will be unchanged"
}

Say a user agent wants to change "title" from "Goodbye!" to "Hello!", add a new "phoneNumber" member, remove "familyName" from the "author" object, and replace the "tags" array so it no longer includes the word "sample". It would send this request:

PATCH /my/resource HTTP/1.1
Host: example.org
Content-Type: application/merge-patch+json

{
  "title": "Hello!",
  "phoneNumber": "+01-123-456-7890",
  "author": {
"familyName": null
  },
  "tags": [ "example" ]
}

And the resulting JSON document is:

{
  "title": "Hello!",
  "author" : {
"givenName" : "John"
  },
  "tags": [ "example" ],
  "content": "This will be unchanged",
  "phoneNumber": "+01-123-456-7890"
}

Main character energy ✨

4. IANA Considerations 📚

This spec registers an additional MIME media type 🎀 Here's the registration, verbatim:

   Type name: application

   Subtype name: merge-patch+json

   Required parameters: None

   Optional parameters: None

   Encoding considerations: Resources that use the "application/
   merge-patch+json" media type are required to conform to the
   "application/json" media type and are therefore subject to the
   same encoding considerations specified in Section 8 of [RFC7159].

   Security considerations: As defined in this specification

   Published specification: This specification.

   Applications that use this media type: None currently known.

   Additional information:

      Magic number(s): N/A

      File extension(s): N/A

      Macintosh file type code(s): TEXT

   Person & email address to contact for further information: IESG

   Intended usage: COMMON

   Restrictions on usage: None

   Author: James M. Snell <jasnell@gmail.com>

   Change controller: IESG

5. Security Considerations 🔐

Okay, this section is serious, so buckle up 😭

The "application/merge-patch+json" media type lets user agents signal that they want the server to figure out the specific set of change operations to apply to a target resource. That means it's the server's job to decide whether any given change is appropriate, AND whether the user agent is authorized to ask for it. How those decisions get made is out of scope for this spec 🚨

Also, every security consideration in Section 5 of [RFC5789] applies to all uses of the HTTP PATCH method with the "application/merge-patch+json" media type. Read those too, no skipping 💀

6. References 🧚

6.1. Normative References 💜

[RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
           Interchange Format", RFC 7159, March 2014,
           <http://www.rfc-editor.org/info/rfc7159>.

6.2. Informative References 🌸

[RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
           5789, March 2010,
           <http://www.rfc-editor.org/info/rfc5789>.

Appendix A. Example Test Cases 🧪

These are the test cases, verbatim. Each row shows ORIGINAL, PATCH, and RESULT, so you can check your implementation against them 🍓

ORIGINAL        PATCH            RESULT
------------------------------------------
{"a":"b"}       {"a":"c"}       {"a":"c"}

{"a":"b"}       {"b":"c"}       {"a":"b",
                                 "b":"c"}

{"a":"b"}       {"a":null}      {}

{"a":"b",       {"a":null}      {"b":"c"}
 "b":"c"}

{"a":["b"]}     {"a":"c"}       {"a":"c"}

{"a":"c"}       {"a":["b"]}     {"a":["b"]}

{"a": {         {"a": {         {"a": {
  "b": "c"}       "b": "d",       "b": "d"
}                 "c": null}      }
                }               }

{"a": [         {"a": [1]}      {"a": [1]}
  {"b":"c"}
 ]
}

["a","b"]       ["c","d"]       ["c","d"]

{"a":"b"}       ["c"]           ["c"]

{"a":"foo"}     null            null

{"a":"foo"}     "bar"           "bar"

{"e":null}      {"a":1}         {"e":null,
                                 "a":1}

[1,2]           {"a":"b",       {"a":"b"}
                 "c":null}

{}              {"a":            {"a":
                 {"bb":           {"bb":
                  {"ccc":          {}}}
                   null}}}

Acknowledgments 🫶

Lots of people contributed big ideas to this document. They include, but aren't limited to, James Manger, Matt Miller, Carsten Bormann, Bjoern Hoehrmann, Pete Resnick, and Richard Barnes. Thank you, legends 👑

Authors' Addresses 💌

Paul Hoffman
VPN Consortium

EMail: paul.hoffman@vpnc.org


James M. Snell

EMail: jasnell@gmail.com
📦 where this page comes from