Internet Engineering Task Force (IETF)
RFC 6901
分類 Standards Track
ISSN 2070-1721
編集 P. Bryan, Ed. Salesforce.com;
K. Zyp SitePen (USA);
M. Nottingham, Ed. Akamai;
発行 2013 年 4 月

JavaScript Object Notation (JSON) Pointer

要約

JSON Pointer は JavaScript Object Notation (JSON) 文書の中の特定の値を参照するための文字列の構文を規定する。 JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document.

このメモの位置付け

これは、 Internet Standards Track 文書である。 This is an Internet Standards Track document.

この文書は、 IETF よる成果物であり, IETF コミュニティの合意を表現するものである。 それは、公開の評価を受け, IESG から発行が承認されたものである。 Internet 標準についての更なる情報は RFC5741 2 節 に見られる。 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.

この文書の現在の位置付け, 正誤表, フィードバックの仕方についての情報は、 http://www.rfc-editor.org/info/rfc6901 から得られる。 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.

著作権の告知

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

この文書は、その発行の日付から有効な、 BCP 78, および IETF Trust の IETF Documents に対する Legal Provisions Relating の対象になる( http://trustee.ietf.org/license-info )。 これらの文書には,この文書に関するあなたの権利と制約条項が述べらているので、入念に査読されたし。 この文書から取り出された Code Components は、 Trust Legal Provisions の Section 4.e に述べられるように, Simplified BSD License テキストを含んでいなければならず、 Simplified BSD License に記されるように,無保証で提供される。 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.

1. 概要

この仕様は、 JavaScript Object Notation (JSON) 文書 [RFC4627] の中の特定の値を参照するための文字列の構文, JSON Pointer を規定する。 JSON Pointer は、 JSON 文字列値でも, Uniform Resource Identifier (URI) [RFC3986] の素片識別子でも,容易に表記し得るように意図されている。 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. 2. Conventions

2. 表記規約

この文書におけるキーワード: 「〜しなければならない」 = “MUST”, 「〜すべきである」 = “SHOULD”, は、 [RFC2119] に則って解釈されるものとする。 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].

この仕様は、規定の構文規則の記述に ABNF 記法( Augmented Backus Naur Form ) [RFC5234] を用いる。 This specification expresses normative syntax rules using Augmented Backus-Naur Form (ABNF) [RFC5234] notation.

3. 構文

JSON Pointer は、それぞれの先頭に文字 '/' ( %x2F )が付与された, 0 個以上の参照トークン( reference-token )の並びからなる, Unicode 文字列( [RFC4627], 3 節 参照)である。 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 Pointer においては、文字 '~' ( %x7E ), 文字 '/' ( %x2F ) は 特殊な意味を持たされているので、参照トークンの中では,それぞれ '~0', '~1' に符号化しておく必要がある。 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.

JSON Pointer の ABNF 構文は次で与えられる: The ABNF syntax of a JSON Pointer is:

json-pointer    = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
   ; %x2F ( '/' )と %x7E ( '~' )は unescaped から除外される
escaped         = "~" ( "0" / "1" )
   ; それぞれ '~' と '/' を表す

この構文に適合しない JSON Pointer 値はエラー状態とされる( 7 節 を見よ)。 It is an error condition if a JSON Pointer value does not conform to this syntax (see Section 7).

JSON Pointer はバイト列ではなく,文字列で指定されるものであることに注意。 Note that JSON Pointers are specified in characters, not as bytes.

4. 評価

JSON Pointer の評価は、 JSON 文書のルート値 【根元のオブジェクト/配列】 への参照から開始され,文書内の何らかの値への参照で完結する。 JSON Pointer の中のそれぞれの参照トークンは,記された順に評価される。 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.

各参照トークンの評価においては、最初に文字エスケープを復号する。 この復号では、先に文字並び '~1' を '/' に変換してから,文字並び '~0' を '~' に変換する。 この順序の置換により、 '~01' が '~1' に変換された後, '/' に変換されてしまう誤りは避けられるようになる(文字列 '~01' は正しく '~1' に変換されるようになる)。 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).

参照トークンは、次の規則に従って,現在の参照先を変更する: The reference token then modifies which value is referenced according to the following scheme:

配列 index の ABNF 構文は次で与えられる: The ABNF syntax for array indices is:

array-index = %x30 / ( %x31-39 *(%x30-39) )
              ; "0", または数字。ただし、先頭の "0" は不可

実装は、 JSON Pointer の各参照トークンを文書の内容に照らして順に評価し、実際の値に解決できない参照トークンに遭遇した際には,それをエラー状態とする。 例えば、配列に対する非数値トークンによる参照は,エラー状態になる。 詳細は 7 節 に。 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.

配列 index における文字 '-' の利用は、定義により,配列の存在しない要素を参照することから、常にそのようなエラー状態となる。 したがって, JSON Pointer を利用するアプリケーションは、何らかの用をなすのであれば,その文字がどのように扱われるべきか指定する必要がある。 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 Pointer アプリケーションから特に動作が規定されていないエラー状態に際しては、評価は終了となる。 Any error condition for which a specific action is not defined by the JSON Pointer application results in termination of evaluation.

5. JSON 文字列による表現

JSON Pointer は、 JSON 文字列値により表現し得る。 その際には、 [RFC4627], 2.5 節 に則り,すべての 引用符 '"' (%x22), バックスラッシュ '\' (%x5C), 制御文字 (%x00-1F) は,エスケープされなければならない 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 Pointer として処理する際には、その前に,バックスラッシュによるエスケープは復号されなければならないことに注意。 Note that before processing a JSON string as a JSON Pointer, backslash escape sequences must be unescaped.

次のような JSON 文書が与えられたとするとき: For example, given the JSON document

{
   "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
}

次のテキストの各行の先頭に記された JSON 文字列を評価した結果は,同じ行に後続して記された値への参照になる: The following JSON strings evaluate to the accompanying values:

""           // 文書全体
"/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

6. URI 素片識別子による表現

JSON Pointer は、 URI 素片識別子により表現し得る。 そのためには、 UTF-8 [RFC3629] によりオクテット列に符号化してから、 [RFC3986] の規定により素片識別子に許容されない すべての文字(オクテット)を,パーセント符号化する。 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 Pointer を利用するメディア型は、その素片識別子の構文として(通常は,その登録 [RFC6838] の際に),明示的に JSON Pointer を指定する必要があることに注意。 文書が JSON であるからといって、その素片識別子の構文に JSON Pointer を利用し得ることにはならないので。 特に、 application/json における素片識別子の構文は JSON Pointer ではない。 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.

上のものと同じ文書例に対し、次のテキストの各行の先頭に記された URI 素片識別子を評価した結果は,同じ行に後続して記された値への参照になる: Given the same example document as above, the following URI fragment identifiers evaluate to the accompanying values:

#            // 文書全体
#/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

7. エラーの取り扱い

エラー状態に際しては、 JSON Pointer の評価は完了できなくなる。 In the event of an error condition, evaluation of the JSON Pointer fails to complete.

エラー状態には、少なくとも,以下のものが含まれる: Error conditions include, but are not limited to:

この仕様は、エラーの取り扱いを規定しない。 JSON Pointer のアプリケーションは、個々の種類のエラーがもたらす影響とその取り扱いについて,指定するべきである。 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.

例えば アプリケーションは、エラーに遭遇した際に,ポインタ処理を停止させることもあれば, 何らかの既定の値を補完することも考えられる。 For example, some applications might stop pointer processing upon an error, while others may attempt to recover from missing values by inserting default ones.

8. 保安上の考慮

JSON Pointer が実際の JSON 値を参照する保証はない。 したがって, JSON Pointer を利用するアプリケーションには、そのような状況に際してのふるまいが予め規定されるべきである。 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 Pointer は NUL 文字 (Unicode U+0000) も含み得ることに注意。 NUL が文字列の終端を指示するプログラミング言語においては,混同しないように注意を払う必要がある。 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.

9. 謝辞

この仕様への 提案, フィードバック, 適切な言い回しを寄せられた次の方々に感謝する: 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.

10. 参照文献

10.1. 文献(規定)

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3629]
Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
[RFC4627]
Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5234]
Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.

10.2. 文献(参考)

[RFC6838]
Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, January 2013.