Internet Engineering Task Force (IETF) P. Hoffman
Request for Comments: 7386 VPN Consortium
Category: Standards Track J. Snell
ISSN: 2070-1721 October 2014
Internet Engineering Task Force (IETF) P. Hoffman
Request for Comments: 7386 VPN Consortium
Category: Standards Track J. Snell
ISSN: 2070-1721 October 2014
JSON Merge Patch
JSON合并补丁
Abstract
摘要
This specification defines the JSON merge patch format and processing rules. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content.
本规范定义了JSON合并补丁格式和处理规则。合并补丁格式主要用于HTTP补丁方法，作为描述对目标资源内容的一组修改的手段。
Status of This Memo
关于下段备忘
This is an Internet Standards Track document.
这是一份互联网标准跟踪文件。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。有关互联网标准的更多信息，请参见RFC 5741第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7386.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc7386.
Copyright Notice
版权公告
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2014 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
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 . . . . . . . . . . . . . . . . . . . . . . . . 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
This specification defines the JSON merge patch document format, processing rules, and associated MIME media type identifier. The merge patch format is primarily intended for use with the HTTP PATCH method [RFC5789] as a means of describing a set of modifications to a target resource's content.
此规范定义JSON合并修补程序文档格式、处理规则和相关MIME媒体类型标识符。合并补丁格式主要用于HTTP补丁方法[RFC5789]，作为描述对目标资源内容的一组修改的手段。
A JSON merge patch document describes changes to be made to a target JSON document using a syntax that closely mimics the document being modified. Recipients of a merge patch document determine the exact set of changes being requested by comparing the content of the provided patch against the current content of the target document. If the provided merge patch contains members that do not appear within the target, those members are added. If the target does contain the member, the value is replaced. Null values in the merge patch are given special meaning to indicate the removal of existing values in the target.
JSON合并补丁文档描述了使用与正在修改的文档非常相似的语法对目标JSON文档所做的更改。合并修补程序文档的收件人通过将提供的修补程序的内容与目标文档的当前内容进行比较来确定请求的确切更改集。如果提供的合并修补程序包含未出现在目标中的成员，则会添加这些成员。如果目标确实包含该成员，则替换该值。合并补丁中的空值具有特殊意义，以指示删除目标中的现有值。
For example, given the following original JSON document:
例如，给定以下原始JSON文档：
{
"a": "b",
"c": {
"d": "e",
"f": "g"
}
}
{
"a": "b",
"c": {
"d": "e",
"f": "g"
}
}
Changing the value of "a" and removing "f" can be achieved by sending:
更改“a”的值并删除“f”可以通过发送以下命令来实现：
PATCH /target HTTP/1.1
Host: example.org
Content-Type: application/merge-patch+json
PATCH /target HTTP/1.1
Host: example.org
Content-Type: application/merge-patch+json
{
"a":"z",
"c": {
"f": null
}
}
{
"a":"z",
"c": {
"f": null
}
}
When applied to the target resource, the value of the "a" member is replaced with "z" and "f" is removed, leaving the remaining content untouched.
当应用到目标资源时，“a”成员的值将替换为“z”，而“f”将被删除，剩下的内容将保持不变。
This design means that merge patch documents are suitable for describing modifications to JSON documents that primarily use objects for their structure and do not make use of explicit null values. The merge patch format is not appropriate for all JSON syntaxes.
这种设计意味着合并补丁文档适合描述对JSON文档的修改，这些文档主要使用对象作为其结构，而不使用显式空值。合并补丁格式不适用于所有JSON语法。
JSON merge patch documents describe, by example, a set of changes that are to be made to a target resource. Recipients of merge patch documents are responsible for comparing the merge patch with the current content of the target resource to determine the specific set of change operations to be applied to the target.
JSON合并补丁文档举例说明了要对目标资源进行的一组更改。合并修补程序文档的收件人负责将合并修补程序与目标资源的当前内容进行比较，以确定要应用于目标的特定更改操作集。
To apply the merge patch document to a target resource, the system realizes the effect of the following function, described in pseudocode. For this description, the function is called MergePatch, and it takes two arguments: the target resource document and the merge patch document. The Target argument can be any JSON value or undefined. The Patch argument can be any JSON value.
为了将合并补丁文档应用于目标资源，系统实现以下功能的效果，如伪代码所述。对于这种描述，该函数称为MergePatch，它有两个参数：目标资源文档和合并补丁文档。目标参数可以是任何JSON值，也可以是未定义的。补丁参数可以是任何JSON值。
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
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
There are a few things to note about the function. If the patch is anything other than an object, the result will always be to replace the entire target with the entire patch. Also, it is not possible to patch part of a target that is not an object, such as to replace just some of the values in an array.
关于这个函数，有几点需要注意。如果面片不是对象，结果将始终是用整个面片替换整个目标。此外，不可能修补非对象的目标部分，例如仅替换数组中的一些值。
The MergePatch operation is defined to operate at the level of data items, not at the level of textual representation. There is no expectation that the MergePatch operation will preserve features at the textual-representation level such as white space, member ordering, number precision beyond what is available in the target's implementation, and so forth. In addition, even if the target implementation allows multiple name/value pairs with the same name, the result of the MergePatch operation on such objects is not defined.
MergePatch操作定义为在数据项级别上操作，而不是在文本表示级别上操作。不期望MergePatch操作将保留文本表示级别的功能，例如空白、成员顺序、数字精度超出目标实现中可用的范围等。此外，即使目标实现允许使用相同名称的多个名称/值对，也不会定义对此类对象执行MergePatch操作的结果。
Given the following example JSON document:
给出以下JSON文档示例：
{
"title": "Goodbye!",
"author" : {
"givenName" : "John",
"familyName" : "Doe"
},
"tags":[ "example", "sample" ],
"content": "This will be unchanged"
}
{
"title": "Goodbye!",
"author" : {
"givenName" : "John",
"familyName" : "Doe"
},
"tags":[ "example", "sample" ],
"content": "This will be unchanged"
}
A user agent wishing to change the value of the "title" member from "Goodbye!" to the value "Hello!", add a new "phoneNumber" member, remove the "familyName" member from the "author" object, and replace the "tags" array so that it doesn't include the word "sample" would send the following request:
用户代理希望将“title”成员的值从“再见！”更改为“Hello！”，添加新的“phoneNumber”成员，从“author”对象中删除“familyName”成员，并替换“tags”数组，使其不包含单词“sample”，将发送以下请求：
PATCH /my/resource HTTP/1.1
Host: example.org
Content-Type: application/merge-patch+json
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" ]
}
{
"title": "Hello!",
"phoneNumber": "+01-123-456-7890",
"author": {
"familyName": null
},
"tags": [ "example" ]
}
The resulting JSON document would be:
生成的JSON文档将是：
{
"title": "Hello!",
"author" : {
"givenName" : "John"
},
"tags": [ "example" ],
"content": "This will be unchanged",
"phoneNumber": "+01-123-456-7890"
}
{
"title": "Hello!",
"author" : {
"givenName" : "John"
},
"tags": [ "example" ],
"content": "This will be unchanged",
"phoneNumber": "+01-123-456-7890"
}
This specification registers the following additional MIME media types:
本规范注册了以下其他MIME媒体类型：
Type name: application
类型名称：应用程序
Subtype name: merge-patch+json
子类型名称：合并修补程序+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].
编码注意事项：使用“application/merge patch+json”媒体类型的资源需要符合“application/json”媒体类型，因此需要遵守[RFC7159]第8节中规定的相同编码注意事项。
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
Magic number(s): N/A
File extension(s): N/A
File extension(s): N/A
Macintosh file type code(s): TEXT
Macintosh文件类型代码：文本
Person & email address to contact for further information: IESG
联系人和电子邮件地址，以获取更多信息：IESG
Intended usage: COMMON
预期用途：普通
Restrictions on usage: None
使用限制：无
Author: James M. Snell <jasnell@gmail.com>
Author: James M. Snell <jasnell@gmail.com>
Change controller: IESG
更改控制器：IESG
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 be applied to a target resource. As such, it is the server's responsibility to determine the appropriateness of any given change as well as the user agent's authorization to request such changes. How such determinations are made is considered out of the scope of this specification.
“application/merge patch+json”媒体类型允许用户代理指示其意图，以便服务器确定要应用于目标资源的特定更改操作集。因此，服务器有责任确定任何给定更改的适当性以及用户代理请求此类更改的授权。如何进行此类测定不在本规范范围内。
All of the security considerations discussed in Section 5 of [RFC5789] apply to all uses of the HTTP PATCH method with the "application/merge-patch+json" media type.
[RFC5789]第5节中讨论的所有安全注意事项适用于“应用程序/合并修补程序+json”媒体类型的HTTP修补程序方法的所有使用。
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7159]Bray，T.，“JavaScript对象表示法（JSON）数据交换格式”，RFC 7159，2014年3月<http://www.rfc-editor.org/info/rfc7159>.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010, <http://www.rfc-editor.org/info/rfc5789>.
[RFC5789]Dusseault，L.和J.Snell，“HTTP的补丁方法”，RFC 5789，2010年3月<http://www.rfc-editor.org/info/rfc5789>.
ORIGINAL PATCH RESULT
------------------------------------------
{"a":"b"} {"a":"c"} {"a":"c"}
ORIGINAL PATCH RESULT
------------------------------------------
{"a":"b"} {"a":"c"} {"a":"c"}
{"a":"b"} {"b":"c"} {"a":"b",
"b":"c"}
{"a":"b"} {"b":"c"} {"a":"b",
"b":"c"}
{"a":"b"} {"a":null} {}
{"a":"b"} {"a":null} {}
{"a":"b", {"a":null} {"b":"c"}
"b":"c"}
{"a":"b", {"a":null} {"b":"c"}
"b":"c"}
{"a":["b"]} {"a":"c"} {"a":"c"}
{"a":["b"]} {"a":"c"} {"a":"c"}
{"a":"c"} {"a":["b"]} {"a":["b"]}
{"a":"c"} {"a":["b"]} {"a":["b"]}
{"a": { {"a": { {"a": {
"b": "c"} "b": "d", "b": "d"
} "c": null} }
} }
{"a": { {"a": { {"a": {
"b": "c"} "b": "d", "b": "d"
} "c": null} }
} }
{"a": [ {"a": [1]} {"a": [1]}
{"b":"c"}
]
}
{"a": [ {"a": [1]} {"a": [1]}
{"b":"c"}
]
}
["a","b"] ["c","d"] ["c","d"]
[“a”，“b”][“c”，“d”][“c”，“d”]
{"a":"b"} ["c"] ["c"]
{"a":"b"} ["c"] ["c"]
{"a":"foo"} null null
{"a":"foo"} null null
{"a":"foo"} "bar" "bar"
{"a":"foo"} "bar" "bar"
{"e":null} {"a":1} {"e":null,
"a":1}
{"e":null} {"a":1} {"e":null,
"a":1}
[1,2] {"a":"b", {"a":"b"}
"c":null}
[1,2] {"a":"b", {"a":"b"}
"c":null}
{} {"a": {"a":
{"bb": {"bb":
{"ccc": {}}}
null}}}
{} {"a": {"a":
{"bb": {"bb":
{"ccc": {}}}
null}}}
Acknowledgments
致谢
Many people contributed significant ideas to this document. These people include, but are not limited to, James Manger, Matt Miller, Carsten Bormann, Bjoern Hoehrmann, Pete Resnick, and Richard Barnes.
许多人对这份文件提出了重要的想法。这些人包括但不限于詹姆斯·马格、马特·米勒、卡斯滕·鲍曼、比约恩·霍尔曼、皮特·雷斯尼克和理查德·巴恩斯。
Authors' Addresses
作者地址
Paul Hoffman VPN Consortium
保罗·霍夫曼VPN联盟
EMail: paul.hoffman@vpnc.org
EMail: paul.hoffman@vpnc.org
James M. Snell
詹姆斯·M·斯内尔
EMail: jasnell@gmail.com
EMail: jasnell@gmail.com