JSON Reference

JSON Reference allows a JSON value to reference another value in a JSON document. This module implements utilities for exploring these objects.


A JSON Reference is a mapping with a unique key $ref, which value is a JSON Pointer. For example, this object:

  "foo": {"$ref": "#/bar"},
  "bar": true

Can be resolved as:

  "foo": true,
  "bar": true

They are some ways to resolve JSON Reference. The simpliest one:

from jsonspec.reference import resolve

obj = {
    'foo': ['bar', {'$ref': '#/sub'}, {'$ref': 'obj2#/sub'}],
    'sub': 'baz'

assert 'bar' == resolve(obj, '#/foo/0')
assert 'baz' == resolve(obj, '#/foo/1')
assert 'quux' == resolve(obj, '#/foo/2', {
    'obj2': {'sub': 'quux'}

You may do not already know which documents you will need to resolve your document. For this case, you can plug providers. Actually, these are:

provider usage
PkgProvider load any provider from setuptools entrypoints
FilesystemProvider load documents from filesystem
SpecProvider load latest JSON Schema specs.

For example, your document refer to stored documents on your filesystem:

from jsonspec.reference import Registry
from jsonspec.reference.providers import FileSystemProvider

obj = {
    'foo': {'$ref': 'my:doc#/sub'}
provider = FileSystemProvider('/path/to/my/doc', prefix='my:doc')

resolve(obj, '#/foo/2', {
    'obj2': {'sub': 'quux'}


reference.resolve(obj, pointer, registry=None)

resolve a local object

  • obj – the local object.
  • pointer (DocumentPointer, str) – the pointer
  • registry (Provider, dict) – the registry. It mays be omited if inner json references document don’t refer to other documents.


Once pointer is extracted, it won’t follow sub mapping /element! For example, the value of:

value = resolve({
    'foo': {'$ref': '#/bar'},
    'bar': [{'$ref': '#/baz'}],
    'baz': 'quux',
}, '#/foo')


assert value == [{'$ref': '#/baz'}]

and not:

assert value == ['quux']
class reference.Registry(provider=None)

Register all documents.

  • provider – all documents
  • provider – Provider, dict

Resolve from documents.

Parameters:pointer (DocumentPointer) – foo
class reference.LocalRegistry(doc, provider=None)

Scoped registry to a local document.

  • doc – the local document
  • provider – all documents
  • provider – Provider, dict
  • key – current document identifier




Extracts $ref of object.

class reference.util.Mapping

A Mapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for __getitem__, __iter__, and __len__.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
values() → list of D's values
class reference.util.MutableMapping

A MutableMapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for __getitem__, __setitem__, __delitem__, __iter__, and __len__.

clear() → None. Remove all items from D.
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v


class reference.NotFound

raises when a document is not found

class reference.Forbidden

raises when a trying to replace <local> document

Defining providers

class reference.providers.PkgProvider(namespace=None, configuration=None)

Autoload providers declared into setuptools entry_points.

For example, with this setup.cfg:

jsonspec.reference.contributions =
    spec = jsonspec.misc.providers:SpecProvider
class reference.providers.FilesystemProvider(directory, prefix=None)

Exposes json documents stored into filesystem.

for example, with prefix=my:pref: and directory=my/directory, this filesystem will be loaded as:

    foo.json        -> my:pref:foo#
    bar.json        -> my:pref:bar#
        quux.json   -> my:pref:baz/quux#
class reference.providers.SpecProvider

Provides specs of http://json-schema.org/