Module `Json_pointer`Source

RFC 6901 JSON Pointers for Jsont JSON values.

A JSON Pointer is an address for one location inside a JSON document, in the way a file path is an address for a file. It is a sequence of string tokens, written with each token prefixed by /. A token's meaning depends on the value being traversed. It is a member name for an object and an array index for an array.

In the document

{"users": [{"name": "Ada"}, {"name": "Grace"}], "active": true}

/users/0/name is "Ada", /users is the whole array, and the empty pointer is the document itself. The JSON value decides how a token is read, so numeric object member names remain ordinary tokens and /0 is the member named "0" of an object and element zero of an array. The token - is special only against an array, where it denotes the position after the last element.

Two characters are escaped inside a token. ~1 stands for / and ~0 for ~, so /a~1b is the member named "a/b". of_string and to_string apply the escaping, and the token-level functions are in Token.

Parsing a pointer does not check that its target exists. Resolution happens in get, get_result and find. The RFC 6902 JSON Patch operations build new documents from a pointer, path and its companions lift a pointer into a Jsont.t codec, and Jmap adds the RFC 8620 wildcard extension.

See the tutorial for a worked introduction.

Sourcemodule Token : sig ... end

Sourcetype t

A JSON Pointer.

Sourceval root : t

The empty pointer, which identifies the whole document.

Sourceval is_root : t -> bool

is_root p is true exactly when p is root.

Sourceval of_tokens : Token.t list -> t

of_tokens tokens is the pointer made of tokens, in traversal order.

Raises Jsont.Error if a token is not valid UTF-8.

Sourceval tokens : t -> Token.t list

tokens p returns p's unescaped tokens in traversal order.

Sourceval (/) : t -> Token.t -> t

p / token appends token to p.

Raises Jsont.Error if token is not valid UTF-8.

Sourceval append : t -> Token.t -> t

append p token is p / token.

Sourceval concat : t -> t -> t

concat a b appends all of b's tokens to a.

Sourceval parent : t -> t option

parent p drops p's last token, or is None for root.

Sourceval last : t -> Token.t option

last p is p's last token, or None for root.

Parsing and formatting

Sourceval of_string : string -> t

of_string s parses the JSON Pointer string representation s.

Raises Jsont.Error if a nonempty s does not start with / or a token contains invalid UTF-8 or an invalid escape sequence.

Sourceval of_string_result : string -> (t, string) result

of_string_result is of_string with errors returned as strings.

Sourceval to_string : t -> string

to_string p is p in JSON Pointer string representation.

Sourceval of_uri_fragment : string -> t

of_uri_fragment s parses the percent-encoded content of a URI fragment. The leading # is not part of s. Percent-decoding is performed before JSON Pointer token unescaping.

Raises Jsont.Error on invalid percent encoding or pointer syntax.

Sourceval of_uri_fragment_result : string -> (t, string) result

of_uri_fragment_result is of_uri_fragment with errors returned as strings.

Sourceval to_uri_fragment : t -> string

to_uri_fragment p is the percent-encoded URI fragment content for p, without the leading #.

Sourceval pp : Format.formatter -> t -> unit

pp formats the JSON Pointer string representation.

Sourceval equal : t -> t -> bool

equal a b is true exactly when a and b have equal tokens.

Sourceval compare : t -> t -> int

compare orders pointers lexicographically by token.

Sourceval of_path : Jsont.Path.t -> t

of_path path converts a Jsont.Path.t to a JSON Pointer.

JSON Pointer syntax does not distinguish a numeric object member from an array index; the resulting token is interpreted from the JSON value when evaluated. There is consequently no context-free inverse conversion.

Raises Jsont.Error if path contains a negative array index or an object member name that is not valid UTF-8.

Evaluation

Sourceval get : t -> Jsont.json -> Jsont.json

get p json returns the value identified by p.

Raises Jsont.Error if p cannot be resolved, including when a referenced object member name is not unique.

Sourceval get_result : t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result

get_result is get with errors returned in the result.

Sourceval find : t -> Jsont.json -> Jsont.json option

find p json is Some value if p resolves and None otherwise.

JSON Patch operations

Sourceval add : t -> Jsont.json -> value:Jsont.json -> Jsont.json

add path json ~value implements the RFC 6902 add operation.

It replaces or creates an object member, inserts at an array index, and appends to an array when the final token is -. All preceding tokens must identify existing values. The root pointer replaces the document.

Raises Jsont.Error if the target parent cannot be resolved or an array index is out of bounds.

Sourceval remove : t -> Jsont.json -> Jsont.json

remove path json implements the RFC 6902 remove operation.

Raises Jsont.Error if path is root or does not identify an existing value.

Sourceval replace : t -> Jsont.json -> value:Jsont.json -> Jsont.json

replace path json ~value implements the RFC 6902 replace operation. The root pointer replaces the document.

Raises Jsont.Error if path does not identify an existing value.

Sourceval move : from:t -> path:t -> Jsont.json -> Jsont.json

move ~from ~path json implements the RFC 6902 move operation. Identical source and destination pointers leave json unchanged.

Raises Jsont.Error if from does not resolve, path's parent does not resolve, or from is a proper prefix of path.

Sourceval copy : from:t -> path:t -> Jsont.json -> Jsont.json

copy ~from ~path json implements the RFC 6902 copy operation.

Sourceval test : t -> Jsont.json -> expected:Jsont.json -> bool

test path json ~expected implements the RFC 6902 test comparison. It returns false whenever path does not resolve, including on errors such as a non-unique object member name.

Jsont codecs and queries

Sourceval jsont : t Jsont.t

A codec for JSON Pointer string representations.

Sourceval jsont_uri_fragment : t Jsont.t

A codec for percent-encoded URI fragment content, without the leading #.

Sourceval path : ?absent:'a -> t -> 'a Jsont.t -> 'a Jsont.t

path p codec extracts the value at p and decodes it with codec. If absent is supplied, it is returned when a referenced member or array element is missing. Invalid indices, incompatible JSON values, duplicate member names, and codec errors are still reported.

The resulting codec is decode-only: encoding through it raises Jsont.Error.

Source

val set_path : 
  ?allow_absent:bool ->
  'a Jsont.t ->
  t ->
  'a ->
  Jsont.json Jsont.t

set_path codec p value produces a codec that replaces the value at p. With allow_absent:true, a missing final object member or the position at the current end of an array may be created; preceding values must still exist.

Sourceval update_path : ?absent:'a -> t -> 'a Jsont.t -> Jsont.json Jsont.t

update_path p codec produces a codec that decodes and re-encodes the value at p. If absent is supplied, that value is inserted when the final target is missing and its parent exists.

Sourceval delete_path : ?allow_absent:bool -> t -> Jsont.json Jsont.t

delete_path p produces a codec that removes the value at p. With allow_absent:true, a missing final object member or array element leaves the input unchanged; preceding tokens must still resolve. The root pointer is rejected.

JMAP result references

Sourcemodule Jmap : sig ... end

RFC 8620 result references.

package json-pointer