JSON Pointer

1. 序論

この仕様は、JSON（ `JavaScript Object Notation^en ）文書 `RFC4627$r の中の特定の値を識別するための文字列の構文，~JSON-Pointerを定義する。 ~JSON-Pointerは、~JSON文字列~値でも, ~URI（ `Uniform Resource Identifier^en ） `RFC3986$r の素片~識別子でも，容易に表出できるように意図されている。 ◎ 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^en ）”, “〜するベキである（ `SHOULD^en ）” ］は、 `RFC2119$r に述べるように解釈されるものとする。 ◎ 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^en ）`RFC5234$r を利用して，規範的な構文~規則を表出する。 ◎ This specification expresses normative syntax rules using Augmented Backus-Naur Form (ABNF) [RFC5234] notation.

3. 構文

~JSON-Pointerは、それぞれの先頭に文字 `/^c' （ `2F^X ）が付与された， 0 個以上の参照~token（ reference-token ）の並びからなる，~Unicode文字列（ `RFC4627$r, § 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においては、［ 文字 `~^l （ `7E^X ） ／ 文字 `/^l （ `2F^X ） ］には特別な意味があるので，参照~tokenの中では［ `~0^l ／ `~1^l ］に符号化しておく必要がある。 ◎ 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
	; 
`2F^X （ `/^l ）と `7E^X （ `~^l ）は `unescaped^c から除外される
◎
%x2F ('/') and %x7E ('~') are excluded from 'unescaped'

escaped
	= "~" ( "0" / "1" )
	; 
それぞれ `~^l と `/^l を表現する
◎
representing '~' and '/', respectively

この構文に適合しない~JSON-Pointer値は~error条件とされる（ § 7 を見よ）。 ◎ It is an error condition if a JSON Pointer value does not conform to this syntax (see Section 7).

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

4. 評価

~JSON-Pointerの評価は、~JSON文書の~root値への参照から始まり，文書~内の何らかの値への参照で完了する。 ~JSON-Pointer内の各~参照~tokenは、記された順に評価される。 ◎ 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.

各~参照~tokenの評価においては、先ず~escapeされた文字を復号する。 これを遂行するときは、先ず文字並び `~1^l を `/^l に置換してから，文字並び `~0^l を `~^l に置換する。 この順序で置換することで、 `~01^l が `~1^l に置換されてから `/^l に置換されてしまう誤りは避けられるようになる（文字列 `~01^l は正しく `~1^l に置換される）。 ◎ 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).

参照~tokenは、次の~~規則に則って，現在の参照-先を改変する： ◎ The reference token then modifies which value is referenced according to the following scheme:

• 現在の参照先の値は~JSON~objである場合 ⇒ 新たな参照先の値は、参照~tokenで識別される名前の~obj~memberになるとする。 ~member名は、~tokenと同じ個数の~Unicode文字からなり, かつ それらの符号位置が~byteごとに等しいとき，~tokenに等しいとされる — いかなる~Unicode文字~正規化も遂行しないこと。 参照先の~member名が~obj内で一意でない場合、参照先の値は未定義とし，評価は失敗したとされる（後述）。 ◎ 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配列である場合、参照~tokenは次のいずれかでなければナラナイ： ◎ o If the currently referenced value is a JSON array, the reference token MUST contain either:

  • 無符号 10 進~整数を表現する，数字のみからなる文字列（下の~ABNFを見よ — 先頭の 0 は許容されないことに注意） ⇒ この場合の新たな参照先の値は、この~tokenで識別される~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
  • 単独の文字 `-^l ⇒ この場合の新たな参照先の値は、配列の最後の要素の後の（存在しない）~memberになるものとする。 ◎ * 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^l, または数字。ただし、先頭の `0^l は不可
◎
"0", or digits without a leading "0"

実装は、~JSON-Pointerの各~参照~tokenを文書の内容に照らして順に評価し、実体的な値に解決できない参照~tokenに~~遭遇した際には，それを~error条件とする。 例えば、配列に対する非数値~tokenによる参照は，~error条件になる。 詳細は § 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における文字 `-^l の利用は、定義により，存在しない配列~要素を参照することから、常にそのような~error条件となる。 したがって，~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応用から特定の動作が定義されていない~error条件は、評価を終了させる。 ◎ 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$r, § 2.5 に則り，次に挙げる文字は すべて~escapeされなければナラナイ ⇒＃ 引用符 `"^l （ `22^X ）, ~backslash `\^l （ `5C^X ）, 制御文字（ `00-1F^X ） ◎ 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として処理する際には、その前に，~backslashによる~escape列は~~展開されなければならないことに注意。 ◎ Note that before processing a JSON string as a JSON Pointer, backslash escape sequences must be unescaped.

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

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

~JSON-Pointerは、~URI素片~識別子により表現できる。 そのためには、~UTF-8 `RFC3629$r により~octet列に符号化してから、 `RFC3986$r により素片~識別子に許容されない すべての文字（~octet）を，~percent符号化する。 ◎ 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を利用する~MIME型は、その素片~識別子の構文として（通例的には，その登録において `RFC6838$r ），明示的に~JSON-Pointerを指定する必要があることに注意。 文書が~JSONであるからといって、その素片~識別子の構文に~JSON-Pointerを利用し得ることにはならないので。 特に、 `application/json^c における素片~識別子の構文は~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.

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

7. ~errorの取扱い

~error条件に際しては、~JSON-Pointerの評価は完了できなくなる。 ◎ In the event of an error condition, evaluation of the JSON Pointer fails to complete.

~error条件には、少なくとも，以下のものが含まれる： ◎ Error conditions include, but are not limited to:

• 無効な~pointer構文 ◎ Invalid pointer syntax
• 存在しない値への参照 ◎ A pointer that references a nonexistent value

この仕様は、~errorをどう取扱うかは定義しない。 ~JSON-Pointerの応用は、 各~種別の~errorに対し，その影響iとその取扱いを指定するベキである。 ◎ 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.

例えば、~errorに際し~pointer処理を停止する応用もあれば，欠落~値に既定の値を挿入して回復しようと試みる応用もあろう。 ◎ 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. ~securityの考慮点

~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 が文字列の終端を~~指示する~programming言語においては，誤解釈しないように~careする必要がある。 ◎ 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. 謝辞

この仕様に案, ~feedback, 言い回しを寄せられた次の方々に： ◎ 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.