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:
anddirectory=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/