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:
- 現在の参照先が JSON オブジェクトである場合、新たな参照先は，参照トークンで識別される名前のオブジェクトメンバになる。 メンバ名は、トークンと同じ個数の Unicode 文字からなり, かつ それらの符号位置がバイトごとに正確に等しくなるとき，トークンに等しいものとされる。 いかなる Unicode 文字正規化も遂行されないものとする。 参照先のメンバ名がオブジェクト内で一意的でない場合、参照先は未定義とし，評価は失敗（後述）とされる。 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).
-
現在の参照先が JSON 配列である場合、参照トークンは次のいずれかでなければならない： o If the currently referenced value is a JSON array, the reference token MUST contain either:
- 符号なし 10 進整数を表現する，数字のみからなる文字列（下の ABNF 参照 — 先頭の 0 は許容されないことに注意）： この場合の新たな参照先は、このトークンが表現する index に位置する，配列の要素になるものとする（ index 0 が最初の要素を指す）。 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
-
単独の文字 '
-' ： この場合の新たな参照先は、配列の最後の要素の後の（存在しない）メンバになるものとする。 * exactly the single character "-", making the new referenced value the (nonexistent) member after the last array element.
配列 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:
- 妥当でないポインタ構文 Invalid pointer syntax
- 存在しない値への参照 A pointer that references a nonexistent value
この仕様は、エラーの取り扱いを規定しない。 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.