jschon.catalog

class jschon.catalog.Catalog(name='catalog', *, resolve_references=True)

The Catalog acts as a schema cache, enabling schemas and subschemas to be indexed, re-used, and cross-referenced by URI.

Parameters:

name (str) –
resolve_references (bool) –

__init__(name='catalog', *, resolve_references=True)

Initialize a Catalog instance.

Parameters:

name (str) – a unique name for this Catalog instance
resolve_references (bool) – passed through to any JSONSChema constructor calls

Return type:

None

add_resource(uri, resource, *, cacheid='default')

Add a (sub)resource to a cache.

Note that this method is called automatically during resource construction.

Parameters:

uri (URI) – the URI identifying the (sub)resource
schema – the JSONResource instance to cache
cacheid (Hashable) – schema cache identifier
resource (JSONResource) –

Return type:

None

add_schema(uri, schema, *, cacheid='default')

Add a (sub)schema to a cache.

Note that this method is called automatically during schema construction.

Parameters:

uri (URI) – the URI identifying the (sub)schema
schema (JSONSchema) – the JSONSchema instance to cache
cacheid (Hashable) – schema cache identifier

Return type:

None

add_uri_source(base_uri, source)

Register a source for loading URI-identified JSON resources.

A base URI of None registers a default source that handles any URI that does not match any registered base URI string.

Parameters:

base_uri (URI | None) – a normalized, absolute URI - including scheme, without a fragment, and ending with '/' or None to match complete URIs
source (Source) – a Source object

Raises:

CatalogError – if base_uri is invalid

Return type:

None

cache(cacheid=None)

Context manager for a schema cache.

Example usage:

with catalog.cache() as cacheid:
    schema = JSONSchema(..., cacheid=cacheid)

The cache and its contents are popped from the catalog upon exiting the with block.

Parameters:: cacheid (Hashable) –
Return type:: AbstractContextManager[Hashable]

create_metadocument(uri, *meta_args, meta_cls=<class 'jschon.vocabulary.Metaschema'>, **meta_kwargs)

Parameters:

uri (URI) –
meta_cls (Type[EvaluableJSON]) –
meta_kwargs (Any) –

Return type:

EvaluableJSON

create_metaschema(uri, default_core_vocabulary_uri=None, *default_vocabulary_uris, **kwargs)

Create, cache and validate a Metaschema.

Parameters:

uri (URI) – the URI identifying the metaschema
default_core_vocabulary_uri (URI | None) – the URI identifying the metaschema’s core Vocabulary, used in the absence of a "$vocabulary" keyword in the metaschema JSON file, or if a known core vocabulary is not present under "$vocabulary"
default_vocabulary_uris (URI) – default Vocabulary URIs, used in the absence of a "$vocabulary" keyword in the metaschema JSON file
kwargs (Any) – additional keyword arguments to pass through to the JSONSchema constructor

Returns:

the newly created Metaschema instance

Raises:

CatalogError – if the metaschema is not valid

Return type:

Metaschema

create_vocabulary(uri, *kwclasses)

Create a Vocabulary object, which may be used by a Metaschema to provide keyword classes used in schema construction.

Parameters:

uri (URI) – the URI identifying the vocabulary
kwclasses (Type[Keyword]) – the Keyword classes constituting the vocabulary

Returns:

the newly created Vocabulary instance

Return type:

Vocabulary

del_resource(uri, *, cacheid='default')

Remove a (sub)resource from a cache.

Parameters:

uri (URI) – the URI identifying the (sub)schema
cacheid (Hashable) – schema cache identifier

Return type:

None

del_schema(uri, *, cacheid='default')

Remove a (sub)schema from a cache.

Parameters:

uri (URI) – the URI identifying the (sub)schema
cacheid (Hashable) – schema cache identifier

Return type:

None

enable_formats(*format_attr)

Enable validation of the specified format attributes.

These may include formats defined in jschon.formats and elsewhere.

Parameters:: format_attr (str) –
Return type:: None

classmethod get_catalog(name='catalog')

Parameters:: name (str) –
Return type:: Catalog

get_metadocument(uri, meta_cls=<class 'jschon.jsonformat.EvaluableJSON'>)

Parameters:

uri (URI) –
meta_cls (Type[EvaluableJSON]) –

Return type:

EvaluableJSON

get_metaschema(uri)

Get a metaschema identified by uri from the '__meta__' cache, or load it from configured sources if not already cached.

Note that metaschemas that do not declare a known core vocabulary in "$vocabulary" must first be created using create_metaschema().

Parameters:

uri (URI) – the URI identifying the metaschema

Raises:

CatalogError – if the object referenced by uri is not a Metaschema, or if it is not valid
JSONSchemaError – if the metaschema is loaded from sources but no known core vocabulary is present in "$vocabulary"

Return type:

Metaschema

get_resource(uri, *, metadocument_uri=None, cacheid='default', cls=<class 'jschon.resource.JSONResource'>, factory=None)

Get a (sub)resource identified by uri from a cache, or load it from a Source if not already cached.

Parameters:

uri (URI) – the URI identifying the (sub)resource
metadocument_uri (URI) – passed to the resource constrructor when loading a new instance from a source; currently this is only used with JSONSchema instances where it is passed as the metaschema_uri parameter
cacheid (Hashable) – schema cache identifier
cls (Union[Type[JSONResource], Type[JSONSchema]]) – The jschon.resource.JSONResource subclass to instantiate
factory (Optional[Callable[[...], JSONResource]]) –

Raises:

CatalogError – if a schema cannot be found for uri, or if the object referenced by uri does not match the type in the cls parameter

Return type:

JSONResource

get_schema(uri, *, metaschema_uri=None, cacheid='default')

Get a (sub)schema identified by uri from a cache, or load it from disk if not already cached.

Parameters:

uri (URI) – the URI identifying the (sub)schema
metaschema_uri (URI | None) – passed to the JSONSchema constructor when loading a new instance from disk
cacheid (Hashable) – schema cache identifier

Raises:

CatalogError – if a schema cannot be found for uri, or if the object referenced by uri is not a JSONSchema

Return type:

JSONSchema

get_vocabulary(uri)

Get a Vocabulary by its uri.

Parameters:: uri (URI) – the URI identifying the vocabulary
Raises:: CatalogError – if uri is not a recognized vocabulary URI
Return type:: Vocabulary

is_format_enabled(format_attr)

Return True if validation is enabled for format_attr, False otherwise.

Return type:: bool

load_json(uri)

Load a JSON-compatible object from the source for uri.

If there are multiple candidate base URIs for uri, the most specific match (i.e. the longest one) is selected.

Parameters:: uri (URI) – a normalized, absolute URI - including scheme, without a fragment
Raises:: CatalogError – if uri is invalid, a source is not available for uri, or if a loading error occurs
Return type:: None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]

resolve_references(cacheid='default')

Ensures that all references in all schemas in a cache have been resolved.

This method is a convenience method for use after instantiatng numerous schemas with resolve_references=False. It ensures that reference resolution will not fail during evaluate() by calling resolve_references() on each schema.

Parameters:: cacheid (Hashable) – The cache in which to resolve all schema references.
Return type:: None

name: str: The unique name of this Catalog instance.

class jschon.catalog.LocalSource(base_dir, **kwargs)

Parameters:

base_dir (Union[str, PathLike]) –
kwargs (Any) –

__call__(relative_path)

Parameters:: relative_path (str) –
Return type:: None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]

__init__(base_dir, **kwargs)

Parameters:

base_dir (str | PathLike) –
kwargs (Any) –

Return type:

None

class jschon.catalog.RemoteSource(base_url, **kwargs)

Parameters:

base_url (URI) –
kwargs (Any) –

__call__(relative_path)

Parameters:: relative_path (str) –
Return type:: None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]

__init__(base_url, **kwargs)

Parameters:

base_url (URI) –
kwargs (Any) –

Return type:

None

class jschon.catalog.Source(suffix=None)

Parameters:: suffix (str) –

__call__(relative_path)

Parameters:: relative_path (str) –
Return type:: None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]

__init__(suffix=None)

Parameters:: suffix (str | None) –
Return type:: None