Internet Engineering Task Force (IETF) P. Bryan, Ed.
Request for Comments: 6901 Salesforce.com
Category: Standards Track K. Zyp
ISSN: 2070-1721 SitePen (USA)
M. Nottingham, Ed.
Akamai
April 2013
Internet Engineering Task Force (IETF) P. Bryan, Ed.
Request for Comments: 6901 Salesforce.com
Category: Standards Track K. Zyp
ISSN: 2070-1721 SitePen (USA)
M. Nottingham, Ed.
Akamai
April 2013
JavaScript Object Notation (JSON) Pointer
JavaScript对象表示法（JSON）指针
Abstract
摘要
JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document.
JSON指针定义了一种字符串语法，用于标识JavaScript对象表示法（JSON）文档中的特定值。
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/rfc6901.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc6901.
Copyright Notice
版权公告
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2013 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. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. JSON String Representation . . . . . . . . . . . . . . . . . . 4
6. URI Fragment Identifier Representation . . . . . . . . . . . . 5
7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
10.1. Normative References . . . . . . . . . . . . . . . . . . . 7
10.2. Informative References . . . . . . . . . . . . . . . . . . 7
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. JSON String Representation . . . . . . . . . . . . . . . . . . 4
6. URI Fragment Identifier Representation . . . . . . . . . . . . 5
7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
10.1. Normative References . . . . . . . . . . . . . . . . . . . 7
10.2. Informative References . . . . . . . . . . . . . . . . . . 7
This specification defines JSON Pointer, a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document [RFC4627]. JSON Pointer is intended to be easily expressed in JSON string values as well as Uniform Resource Identifier (URI) [RFC3986] fragment identifiers.
本规范定义了JSON指针，这是一种字符串语法，用于标识JavaScript对象表示法（JSON）文档[RFC4627]中的特定值。JSON指针旨在以JSON字符串值以及统一资源标识符（URI）[RFC3986]片段标识符轻松表示。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
This specification expresses normative syntax rules using Augmented Backus-Naur Form (ABNF) [RFC5234] notation.
本规范使用增广巴科斯诺尔形式（ABNF）[RFC5234]表示法表示规范性语法规则。
A JSON Pointer is a Unicode string (see [RFC4627], Section 3) containing a sequence of zero or more reference tokens, each prefixed by a '/' (%x2F) character.
JSON指针是一个Unicode字符串（请参见[RFC4627]，第3节），其中包含一系列零个或多个引用标记，每个标记的前缀为“/”（%x2F）字符。
Because the characters '~' (%x7E) and '/' (%x2F) have special meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be encoded as '~1' when these characters appear in a reference token.
因为字符“~”（%x7E）和“/”（%x2F）在JSON指针中有特殊含义，所以当这些字符出现在引用标记中时，“~”需要编码为“~0”，而“/”需要编码为“~1”。
The ABNF syntax of a JSON Pointer is:
JSON指针的ABNF语法为：
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped = "~" ( "0" / "1" )
; representing '~' and '/', respectively
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped = "~" ( "0" / "1" )
; representing '~' and '/', respectively
It is an error condition if a JSON Pointer value does not conform to this syntax (see Section 7).
如果JSON指针值不符合此语法，则为错误条件（请参阅第7节）。
Note that JSON Pointers are specified in characters, not as bytes.
请注意，JSON指针是以字符而不是字节指定的。
Evaluation of a JSON Pointer begins with a reference to the root value of a JSON document and completes with a reference to some value within the document. Each reference token in the JSON Pointer is evaluated sequentially.
JSON指针的计算以引用JSON文档的根值开始，以引用文档中的某个值结束。JSON指针中的每个引用标记都按顺序计算。
Evaluation of each reference token begins by decoding any escaped character sequence. This is performed by first transforming any occurrence of the sequence '~1' to '/', and then transforming any occurrence of the sequence '~0' to '~'. By performing the substitutions in this order, an implementation avoids the error of turning '~01' first into '~1' and then into '/', which would be incorrect (the string '~01' correctly becomes '~1' after transformation).
每个参考令牌的评估都是从解码任何转义字符序列开始的。首先将序列'~1'的任何出现转换为'/'，然后将序列'~0'的任何出现转换为'~'。通过按此顺序执行替换，实现可以避免将“~01”先转换为“~1”，然后再转换为“/”的错误，这是不正确的（字符串“~01”在转换后正确地变成了“~1”）。
The reference token then modifies which value is referenced according to the following scheme:
然后，引用令牌根据以下方案修改引用的值：
o If the currently referenced value is a JSON object, the new referenced value is the object member with the name identified by the reference token. The member name is equal to the token if it has the same number of Unicode characters as the token and their code points are byte-by-byte equal. No Unicode character normalization is performed. If a referenced member name is not unique in an object, the member that is referenced is undefined, and evaluation fails (see below).
o 如果当前引用的值是JSON对象，则新引用的值是具有引用标记标识的名称的对象成员。如果成员名称与令牌具有相同数量的Unicode字符，并且其代码点逐字节相等，则成员名称等于令牌。不执行Unicode字符规范化。如果引用的成员名称在对象中不唯一，则引用的成员未定义，计算失败（请参见下文）。
o If the currently referenced value is a JSON array, the reference token MUST contain either:
o 如果当前引用的值是JSON数组，则引用令牌必须包含：
* characters comprised of digits (see ABNF below; note that leading zeros are not allowed) that represent an unsigned base-10 integer value, making the new referenced value the array element with the zero-based index identified by the token, or
* 由数字组成的字符（请参见下面的ABNF；请注意，不允许使用前导零）表示无符号的base-10整数值，使新引用值成为具有由标记标识的零索引的数组元素，或
* exactly the single character "-", making the new referenced value the (nonexistent) member after the last array element.
* 正好是单个字符“-”，使新引用值成为最后一个数组元素后的（不存在）成员。
The ABNF syntax for array indices is:
数组索引的ABNF语法为：
array-index = %x30 / ( %x31-39 *(%x30-39) )
; "0", or digits without a leading "0"
array-index = %x30 / ( %x31-39 *(%x30-39) )
; "0", or digits without a leading "0"
Implementations will evaluate each reference token against the document's contents and will raise an error condition if it fails to resolve a concrete value for any of the JSON pointer's reference tokens. For example, if an array is referenced with a non-numeric token, an error condition will be raised. See Section 7 for details.
实现将根据文档的内容评估每个引用标记，如果无法解析任何JSON指针引用标记的具体值，则将引发错误条件。例如，如果使用非数字标记引用数组，则会引发错误条件。详见第7节。
Note that the use of the "-" character to index an array will always result in such an error condition because by definition it refers to a nonexistent array element. Thus, applications of JSON Pointer need to specify how that character is to be handled, if it is to be useful.
请注意，使用“-”字符索引数组总是会导致这种错误情况，因为根据定义，它引用的是不存在的数组元素。因此，JSON指针的应用程序需要指定如何处理该字符，如果它有用的话。
Any error condition for which a specific action is not defined by the JSON Pointer application results in termination of evaluation.
JSON指针应用程序未定义特定操作的任何错误条件都会导致计算终止。
A JSON Pointer can be represented in a JSON string value. Per [RFC4627], Section 2.5, all instances of quotation mark '"' (%x22), reverse solidus '\' (%x5C), and control (%x00-1F) characters MUST be escaped.
JSON指针可以用JSON字符串值表示。根据[RFC4627]第2.5节，必须转义引号“”（%x22）、反向索利多金币“\”（%x5C）和控件（%x00-1F）字符的所有实例。
Note that before processing a JSON string as a JSON Pointer, backslash escape sequences must be unescaped.
请注意，在将JSON字符串作为JSON指针处理之前，必须取消反斜杠转义序列的转义。
For example, given the JSON document
例如，给定JSON文档
{
"foo": ["bar", "baz"],
"": 0,
"a/b": 1,
"c%d": 2,
"e^f": 3,
"g|h": 4,
"i\\j": 5,
"k\"l": 6,
" ": 7,
"m~n": 8
}
{
"foo": ["bar", "baz"],
"": 0,
"a/b": 1,
"c%d": 2,
"e^f": 3,
"g|h": 4,
"i\\j": 5,
"k\"l": 6,
" ": 7,
"m~n": 8
}
The following JSON strings evaluate to the accompanying values:
以下JSON字符串计算为附带的值：
"" // the whole document
"/foo" ["bar", "baz"]
"/foo/0" "bar"
"/" 0
"/a~1b" 1
"/c%d" 2
"/e^f" 3
"/g|h" 4
"/i\\j" 5
"/k\"l" 6
"/ " 7
"/m~0n" 8
"" // the whole document
"/foo" ["bar", "baz"]
"/foo/0" "bar"
"/" 0
"/a~1b" 1
"/c%d" 2
"/e^f" 3
"/g|h" 4
"/i\\j" 5
"/k\"l" 6
"/ " 7
"/m~0n" 8
A JSON Pointer can be represented in a URI fragment identifier by encoding it into octets using UTF-8 [RFC3629], while percent-encoding those characters not allowed by the fragment rule in [RFC3986].
JSON指针可以通过使用UTF-8[RFC3629]将其编码为八位字节，而对[RFC3986]中片段规则不允许的字符进行百分比编码，从而在URI片段标识符中表示。
Note that a given media type needs to specify JSON Pointer as its fragment identifier syntax explicitly (usually, in its registration [RFC6838]). That is, just because a document is JSON does not imply that JSON Pointer can be used as its fragment identifier syntax. In particular, the fragment identifier syntax for application/json is not JSON Pointer.
请注意，给定的媒体类型需要明确指定JSON指针作为其片段标识符语法（通常在其注册[RFC6838]中）。也就是说，仅仅因为文档是JSON，并不意味着JSON指针可以用作其片段标识符语法。特别是，application/json的片段标识符语法不是json指针。
Given the same example document as above, the following URI fragment identifiers evaluate to the accompanying values:
给定与上述相同的示例文档，以下URI片段标识符将计算为附带的值：
# // the whole document
#/foo ["bar", "baz"]
#/foo/0 "bar"
#/ 0
#/a~1b 1
#/c%25d 2
#/e%5Ef 3
#/g%7Ch 4
#/i%5Cj 5
#/k%22l 6
#/%20 7
#/m~0n 8
# // the whole document
#/foo ["bar", "baz"]
#/foo/0 "bar"
#/ 0
#/a~1b 1
#/c%25d 2
#/e%5Ef 3
#/g%7Ch 4
#/i%5Cj 5
#/k%22l 6
#/%20 7
#/m~0n 8
In the event of an error condition, evaluation of the JSON Pointer fails to complete.
如果出现错误情况，JSON指针的计算将无法完成。
Error conditions include, but are not limited to:
错误条件包括但不限于：
o Invalid pointer syntax
o 无效的指针语法
o A pointer that references a nonexistent value
o 引用不存在的值的指针
This specification does not define how errors are handled. An application of JSON Pointer SHOULD specify the impact and handling of each type of error.
本规范未定义如何处理错误。JSON指针的应用程序应该指定每种类型错误的影响和处理。
For example, some applications might stop pointer processing upon an error, while others may attempt to recover from missing values by inserting default ones.
例如，一些应用程序可能会在出现错误时停止指针处理，而其他应用程序可能会尝试通过插入默认值来恢复丢失的值。
A given JSON Pointer is not guaranteed to reference an actual JSON value. Therefore, applications using JSON Pointer should anticipate this situation by defining how a pointer that does not resolve ought to be handled.
给定的JSON指针不能保证引用实际的JSON值。因此，使用JSON指针的应用程序应该通过定义如何处理未解析的指针来预测这种情况。
Note that JSON pointers can contain the NUL (Unicode U+0000) character. Care is needed not to misinterpret this character in programming languages that use NUL to mark the end of a string.
请注意，JSON指针可以包含NUL（Unicode U+0000）字符。在使用NUL标记字符串结尾的编程语言中，需要注意不要误解这个字符。
The following individuals contributed ideas, feedback, and wording to this specification:
以下个人为本规范提供了想法、反馈和措辞：
Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin J. Duerst, Bjoern Hoehrmann, James H. Manger, Drew Perttula, and Julian Reschke.
迈克·阿卡尔、卡斯滕·鲍曼、蒂姆·布雷、雅各布·戴维斯、马丁·杜尔斯、比约恩·霍尔曼、詹姆斯·马格尔、德鲁·佩图拉和朱利安·雷什克。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，1997年3月。
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
[RFC3629]Yergeau，F.，“UTF-8，ISO 10646的转换格式”，STD 63，RFC 3629，2003年11月。
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
[RFC3986]Berners Lee，T.，Fielding，R.，和L.Masinter，“统一资源标识符（URI）：通用语法”，STD 66，RFC 3986，2005年1月。
[RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4627]Crockford，D.，“JavaScript对象表示法（json）的应用程序/json媒体类型”，RFC4627，2006年7月。
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5234]Crocker，D.和P.Overell，“语法规范的扩充BNF:ABNF”，STD 68，RFC 5234，2008年1月。
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, January 2013.
[RFC6838]Freed，N.，Klensin，J.和T.Hansen，“媒体类型规范和注册程序”，BCP 13，RFC 6838，2013年1月。
Authors' Addresses
作者地址
Paul C. Bryan (editor) Salesforce.com
保罗·C·布莱恩（编辑）Salesforce.com
Phone: +1 604 783 1481
EMail: pbryan@anode.ca
Phone: +1 604 783 1481
EMail: pbryan@anode.ca
Kris Zyp SitePen (USA)
Kris Zyp SitePen（美国）
Phone: +1 650 968 8787
EMail: kris@sitepen.com
Phone: +1 650 968 8787
EMail: kris@sitepen.com
Mark Nottingham (editor) Akamai
马克·诺丁汉（编辑）Akamai
EMail: mnot@mnot.net
EMail: mnot@mnot.net