jschon.jsonpointer

class jschon.jsonpointer.JSONPointer(*values)

RFC 6901-conformant JSON Pointer implementation.

A JSON pointer is a string representing a reference to some value within a JSON document. It consists of a series of reference tokens each prefixed by "/", each token in turn being the (escaped) JSON object key or the JSON array index at the next node down the path to the referenced value. The empty string "" represents a reference to an entire JSON document.

A JSONPointer instance is an immutable sequence of the unescaped JSON object keys 1 and/or array indices 2 that comprise the path to a referenced value within a JSON document.

A JSONPointer instance is constructed by the concatenation of any number of arguments, each of which can be one of:

  • a string conforming to the RFC 6901 syntax

  • an iterable of unescaped keys (which may itself be a JSONPointer instance)

Two JSONPointer instances compare equal if their key sequences are identical.

The / operator provides a convenient syntax for extending a JSON pointer. It produces a new JSONPointer instance by copying the left-hand argument (a JSONPointer instance) and appending the right-hand argument (an unescaped key, or an iterable of unescaped keys).

Taking an index into a JSONPointer returns the unescaped key at that position. Taking a slice into a JSONPointer returns a new JSONPointer composed of the specified slice of the original’s keys.

1

An unescaped object key is the unmodified form of the key within its mapping. Keys appearing in an RFC 6901 JSON pointer string, on the other hand, are required by the syntax to have reserved characters escaped.

2

Object keys and array indices are uniformly represented as strings and referred to as keys in the JSONPointer class.

Parameters

values (Union[str, Iterable[str]]) –

Return type

JSONPointer

static __new__(cls, *values)

Create and return a new JSONPointer instance, constructed by the concatenation of the given values.

Parameters

values (Union[str, Iterable[str]]) – each value may either be an RFC 6901 string, or an iterable of unescaped keys

Raises

JSONPointerError – if a string argument does not conform to the RFC 6901 syntax

Return type

jschon.jsonpointer.JSONPointer

static escape(key)

Return the escaped form of a JSON object key / array index, suitable for use in an RFC 6901 JSON pointer string.

Parameters

key (str) – an unescaped key

Return type

str

evaluate(document)

Return the value within document at the location referenced by self.

document may be of any type, though if neither a Mapping nor a Sequence, evaluation by any non-empty JSONPointer will always fail.

Parameters

document (Any) – any Python object

Raises

JSONPointerError – if self references a non-existent location within document

Return type

Any

classmethod parse_uri_fragment(value)

Return a new JSONPointer constructed from the RFC 6901 string obtained by decoding value.

value must exclude the initial '#' of the fragment; this allows for sensible interoperation with URI objects.

Parameters

value (str) – a percent-encoded URI fragment

Return type

jschon.jsonpointer.JSONPointer

static unescape(token)

Return the unescaped form of a reference token appearing in an RFC 6901 JSON pointer string

Parameters

token (str) – an RFC 6901 reference token

Return type

str

uri_fragment()

Return a percent-encoded URI fragment representation of self.

The returned string excludes the initial '#' of the fragment; this allows for sensible interoperation with URI objects.

Return type

str