jschon.catalog

class jschon.catalog.Catalog(*versions, default)

The Catalog acts primarily as a schema cache, enabling schemas and subschemas to be indexed, re-used, and cross-referenced by URI. The cache is transparently partitioned by (arbitrary) session identifiers, which may optionally be provided when creating JSONSchema objects.

A Catalog instance is typically initialized by providing one or more JSON Schema version identifiers. Each such identifier triggers the compilation of a corresponding Metaschema object, which in turn provides any referencing schema with all of the Keyword class implementations for that version of the JSON Schema vocabulary.

Parameters
  • versions (str) –

  • default (bool) –

__init__(*versions, default)

Initialize a Catalog instance.

Parameters
  • versions (str) – any of '2019-09', '2020-12'

  • default (bool) – if True, new JSONSchema instances are by default cached in this catalog

Raises

CatalogError – if a supplied version parameter is not recognized

add_directory(base_uri, base_dir)

Register a base URI-to-directory mapping.

This enables JSON objects identified by URIs with a given base URI to be loaded from files within a corresponding directory hierarchy, as described under load_json().

Parameters
  • base_uri (jschon.uri.URI) – a normalized, absolute URI - including scheme, without a fragment, and ending with '/'

  • base_dir (os.PathLike) – a directory path accessible on the file system

Raises

CatalogError – if either base_uri or base_dir is invalid

Return type

None

add_format_validators(validators)

Register a collection of format validators.

In jschon, a given occurrence of the "format" keyword evaluates a JSON instance using a format validation callable, if one has been registered for the applicable format attribute (the keyword’s value). If a validator has not been registered for that format attribute, keyword evaluation simply passes.

Parameters

validators (Mapping[str, Callable[[jschon.json.AnyJSONCompatible], None]]) – a dictionary of FormatValidator callables, keyed by format attribute

Return type

None

add_schema(uri, schema, *, session='default')

Add a (sub)schema to a session cache.

Parameters
Return type

None

create_metaschema(uri, core_vocabulary_uri, *default_vocabulary_uris, **kwargs)

Create, cache and validate a Metaschema.

Parameters
  • uri (jschon.uri.URI) – the URI identifying the metaschema

  • core_vocabulary_uri (jschon.uri.URI) – the URI identifying the metaschema’s core Vocabulary

  • default_vocabulary_uris (jschon.uri.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

Return type

None

create_vocabulary(uri, *kwclasses)

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

Parameters
Return type

None

del_schema(uri, *, session='default')

Remove a (sub)schema from a session cache.

Parameters
  • uri (jschon.uri.URI) – the URI identifying the (sub)schema

  • session (Hashable) – a session identifier

Return type

None

classmethod get_default()

Get the default Catalog instance, if there is one.

Return type

Optional[jschon.catalog.Catalog]

get_format_validator(format_attr)

Get a registered FormatValidator function.

Parameters

format_attr (str) – the format attribute ("format" keyword value) to which the validator applies

Raises

CatalogError – if no format validator is registered for the given format_attr

Return type

Callable[[jschon.json.AnyJSONCompatible], None]

get_schema(uri, *, metaschema_uri=None, session='default')

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

Parameters
  • uri (jschon.uri.URI) – the URI identifying the (sub)schema

  • metaschema_uri (Optional[jschon.uri.URI]) – passed to the JSONSchema constructor when loading a new instance from disk

  • session (Hashable) – a session identifier

Raises

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

Return type

jschon.jsonschema.JSONSchema

get_vocabulary(uri)

Get a Vocabulary by its uri.

Parameters

uri (jschon.uri.URI) – the URI identifying the vocabulary

Raises

CatalogError – if uri is not a recognized vocabulary URI

Return type

jschon.vocabulary.Vocabulary

load_json(uri)

Load a JSON-compatible object from the file corresponding to uri.

The file path is determined by selecting the most specific matching base URI that was registered with add_directory(), and resolving the remainder of uri against the corresponding base directory.

Parameters

uri (jschon.uri.URI) – a normalized, absolute URI - including scheme, without a fragment

Raises

CatalogError – if uri is invalid, or if a corresponding file cannot be found

Return type

jschon.json.AnyJSONCompatible

session(session=None)
Parameters

session (Hashable) –

Return type

AbstractContextManager[Hashable]