JavaScript Object Notation (JSON) Pointer
Extracted elements (14)
Escape decoding must transform '~1' to '/' before transforming '~0' to '~', not the reverse. Performing substitutions in this order prevents '~01' from being incorrectly decoded to '/' (it should become '~1').
The '-' character as an array index always causes an error because it refers to a nonexistent element past the end of the array. Applications that wish to use '-' (e.g., for append semantics) must explicitly define how to handle it; the JSON Pointer specification itself does not assign it a successful resolution.
A media type must explicitly specify JSON Pointer as its fragment identifier syntax (typically in its registration per RFC 6838). The fragment identifier syntax for application/json is not JSON Pointer; adoption is opt-in per media type.
No Unicode character normalization is performed when matching reference tokens to JSON object member names; equality requires the same number of Unicode characters with byte-by-byte equal code points. If a member name is not unique within an object, the referenced member is undefined and evaluation fails.
An application of JSON Pointer SHOULD specify the impact and handling of each type of error condition (invalid pointer syntax, reference to a nonexistent value, etc.). The specification itself does not define how errors are handled.
When the currently referenced value is a JSON array, the reference token MUST contain either digits representing an unsigned base-10 integer (no leading zeros allowed) that identify the zero-based array element, or exactly the single character '-' referring to the nonexistent element after the last.
A JSON Pointer can be represented as a URI fragment identifier by encoding it into UTF-8 octets and then percent-encoding any characters not allowed by the fragment rule in RFC 3986. The empty fragment '#' refers to the whole document.
A JSON Pointer is a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a '/' (%x2F) character. The ABNF is: json-pointer = *( "/" reference-token ), reference-token = *( unescaped / escaped ), where escaped = "~" ( "0" / "1" ).
Array indices follow the ABNF: array-index = %x30 / ( %x31-39 *(%x30-39) ), meaning '0' alone or a nonzero digit followed by any digits — explicitly disallowing leading zeros.
Evaluation begins at the root value of the JSON document and processes each reference token sequentially. For JSON objects, the token identifies the member name via exact Unicode code-point comparison with no normalization. For JSON arrays, the token must be a non-negative base-10 integer index (no leading zeros) or the special character '-'.
The characters '~' (%x7E) and '/' (%x2F) have special meanings in JSON Pointer and must be escaped within reference tokens: '~' encodes as '~0' and '/' encodes as '~1'.
When represented as a JSON string value, all quotation marks, reverse solidus characters, and control characters (%x00-1F) MUST be escaped per RFC 4627 Section 2.5. Backslash escape sequences must be unescaped before the string is processed as a JSON Pointer.
A JSON Pointer is not guaranteed to reference an actual value within a document. Applications using JSON Pointer should anticipate unresolved pointers and define how they ought to be handled rather than assuming resolution always succeeds.
JSON pointers may contain the NUL character (Unicode U+0000). Implementations in languages that use NUL as a string terminator must take care not to misinterpret this character, as it could cause pointer truncation or misbehavior.