JSON Pointer

The JSON Pointer is a string syntax for identifying a specific value within a JSON text document. This syntax can be expressed in JSON string values and Uniform Resource Identifier (URI) fragment identifiers.

The $ref value respects JSON Pointer. For example, this is supported by the GUI: /fhir_1.0.2/bundle.schema.json#/definitions/Bundle_Entry/properties/link.

Example:

  1. Open JSON Configurator. Under Create new file, select "New field".
  2. Select Reference mode.
  3. Specify /fhir_1.0.2/bundle.schema.json#/definitions/Bundle_Entry/properties/link. This loads the node structure on the JSON tree.
Note: In CIS 20.1, the engine does not support JSON Pointer, but does support JSON Path. Because of this, when $ref has a number path, for example, Bundle.schema.json#/definitions/Bundle/allOf[1]/properties/link, the path cannot be used in $ref. In another example, you can input a reference, for example, Account.schema.json#/definitions/Account/extension, and save it. However, the GUI incorrectly displays it.

Syntax

A JSON Pointer is a [Unicode] string containing a sequence of zero or more reference tokens, each prefixed by a "/" (%x2F) character.

If a reference token contains "/" (%x2F) or "\" (%x5C) character, then these characters must each be prefixed (escaped) with a "\" (%x5C) character.

ABNF syntax:

json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-5B / %x5D-10FFFF
escaped = "\" ( "/" / "\" )

It is an error condition if a JSON Pointer value does not conform to this syntax.

Evaluation

Evaluation of a JSON Pointer begins with a reference to the root value of a JSON text document. It completes with a reference to another value within the document. Each reference token in the JSON Pointer is sequentially evaluated.

Evaluation of each reference token begins by unescaping any escaped character sequence; this is performed by the "\" (escape) prefix. The reference token then modifies which value is referenced according to one of these schemes:

  • If the currently referenced value is a JSON object, then the new referenced value is the object member with the name identified by the reference token. If a referenced member name is not unique, then referenced member is undefined.
  • If the currently referenced value is a JSON array, then the reference token must contain an unsigned base-10 integer value. The new referenced value is the array element with the zero-based index identified by the token.
  • If a reference token is being evaluated against a concrete JSON document, then the implementation might evaluate each token against a concrete value. The evaluation is terminated with an error condition if a evaluation fails to resolve a concrete value.

JSON String representation

A JSON Pointer can be represented in a JSON string value. All instances of quotation mark """ (%x22), reverse solidus (backslash) "\"' (%x5C), and control (%x00-1F) characters must be escaped.