JSON Reference¶

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

Note

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'}
})

API¶

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

resolve a local object

Parameters:	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.

Warning

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')

is:

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

and not:

assert value == ['quux']

class reference.Registry(provider=None)¶

Register all documents.

Variables:	provider – all documents provider – Provider, dict

resolve(pointer)¶

Resolve from documents.

Parameters:	pointer (DocumentPointer) – foo

class reference.LocalRegistry(doc, provider=None)¶

Scoped registry to a local document.

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

Utils¶

jsonspec.reference.util¶

reference.util.ref(obj)¶: 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

Exceptions¶

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:

[entry_points]
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:

my/directory/
    foo.json        -> my:pref:foo#
    bar.json        -> my:pref:bar#
    baz/
        quux.json   -> my:pref:baz/quux#

class reference.providers.SpecProvider¶: Provides specs of http://json-schema.org/