jschon.jsonschema

class jschon.jsonschema.JSONSchema(value, *, catalog='catalog', cacheid='default', uri=None, metaschema_uri=None, parent=None, key=None, resolve_references=True)

JSON schema document model.

__init__(value, *, catalog='catalog', cacheid='default', uri=None, metaschema_uri=None, parent=None, key=None, resolve_references=True)

Initialize a JSONSchema instance from the given schema-compatible value.

Parameters:

  • value (Union[bool, Mapping[str, JSONCompatible]]) – a schema-compatible Python object

  • catalog (Union[str, Catalog]) – catalog instance or catalog name

  • cacheid (Hashable) – schema cache identifier

  • uri (URI) – the URI identifying the schema; an "$id" keyword appearing in value will override this

  • metaschema_uri (URI) – the URI identifying the schema’s metaschema; a "$schema" keyword appearing in value will override this

  • parent (JSON) – the parent node of the schema; used internally when creating a subschema

  • key (str) – the index of the schema within its parent; used internally when creating a subschema

  • resolve_references (bool) – if True (the default), then for document root schema, walk the constructed subschemas and resolve all references; set to False when a schema with a temporarily unresolvable reference needs to be instantiated — references MUST be resolved prior to evaluation by calling by calling resolve_references() on each unresolved schema, or resolve_references() on the relevant catalog.

evaluate(instance, result=None)

Evaluate a JSON document and return the evaluation result.

Parameters:

  • instance (JSON) – the JSON document to evaluate

  • result (Result | None) – the current result node; given by keywords when invoking this method recursively

Raises:

JSONSchemaError – if references have not yet been resolved; by default references are resolved during construction

Return type:

Result

get_subschema_cls()
initial_validation_result(instance)
is_format_root()
is_resource_root()
resolve_references()

Walk the entire (sub)schema tree and resolve all references.

By default, this is done during construction, but can be deferred to handle complex mutual reference cases. Calling evaluate() without first resolving rereferences will result in an JSONSchemaError.

Raises:
Return type:

None

property canonical_uri: URI | None

The absolute location of the (sub)schema.

This is not necessarily an ‘absolute URI’, as it may contain a fragment.

data: bool | Dict[str, JSON]

The schema data.

JSON type

data type

boolean

bool

object

dict[str, JSON]
property document_rootschema: JSONSchema

The JSONSchema at the root of the entire document.

If no ancestor schemas contain "$id", this is the same as self.resource_rootschema. If this schema has no self.parentschema, this method returns self.

key: str | None

The index of the schema within its parent.

keywords: Dict[str, Keyword]

A dictionary of the schema’s Keyword objects, indexed by keyword name.

property metaschema: Metaschema

The schema’s Metaschema.

property metaschema_uri: URI | None

The URI identifying the schema’s metaschema.

If not defined on this (sub)schema, the metaschema URI is determined by the parent schema.

parent: JSON | None

The containing JSON or JSONSchema node.

property parentschema: JSONSchema | None

The containing JSONSchema instance.

Note that this is not necessarily the same as self.parent.

property resource_rootschema: JSONSchema

The JSONSchema at the root of the containing resource.

This is the nearest ancestor (including self) containing "$id", or if none exist, it is the same as self.document_rootschema.

type: str

The JSON type of the schema. One of "boolean", "object".

class jschon.jsonschema.Result(schema, instance, *, validating_with=None, parent=None, key=None)

The result of evaluating a JSON document node against a JSON schema node.

The root of a Result tree represents a complete document evaluation result.

Parameters:
__call__(instance, key, schema=None, *, validating_with=None, cls=None)

Yield a subresult for the evaluation of instance. Descend down the evaluation path by key, into schema if given, or within self.schema otherwise.

Extension keywords may provide a custom Result class via cls, which is applied to all nodes within the yielded subtree.

Parameters:
Return type:

ContextManager[Result]

__init__(schema, instance, *, validating_with=None, parent=None, key=None)
Parameters:
Return type:

None

annotate(value)

Annotate the result.

Parameters:

value (None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

collect_annotations(instance=None, key=None)

Return an iterator over annotations produced in this subtree, optionally filtered by instance and/or keyword.

Parameters:

  • instance (JSON | None) –

  • key (str | None) –

Return type:

Iterator[None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]]

collect_errors(instance=None, key=None)

Return an iterator over errors produced in this subtree, optionally filtered by instance and/or keyword.

Parameters:

  • instance (JSON | None) –

  • key (str | None) –

Return type:

Iterator[None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]]

discard()

Indicate that the result should be ignored and discarded.

Return type:

None

fail(error=None)

Mark the result as invalid, optionally with an error.

Parameters:

error (None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

noassert()

Indicate that evaluation passes regardless of validity.

Return type:

None

output(format, **kwargs)

Return the evaluation result in the specified format.

Parameters:

  • format (str) – One of the standard JSON Schema output formats – flag, basic, detailed or verbose – or any format registered with the output_formatter() decorator.

  • kwargs (Any) – Keyword arguments to pass to the output formatter.

Return type:

None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]

pass_()

Mark the result as valid.

A result is initially valid, so this should only need to be called by a keyword when it must reverse a failure.

Return type:

None

refschema(schema)

Set the referenced schema for a by-reference keyword.

This ensures that absolute_uri returns the URI of the referenced schema rather than the referencing keyword.

Parameters:

schema (JSONSchema) –

Return type:

None

sibling(instance, key)

Return a sibling schema node’s evaluation result for instance.

Parameters:

  • instance (JSON) –

  • key (str) –

Return type:

Result | None

property absolute_uri: URI | None

Return the absolute URI of the current schema node.

annotation: JSONCompatible

The annotation value of the result.

children: Dict[Tuple[str, JSONPointer], Result]

Subresults of the current result node, indexed by schema key and instance path.

error: JSONCompatible

The error value of the result.

property globals: Dict
instance: JSON

The instance under evaluation.

key: str | None

The index of the current schema node within its dynamic parent.

parent: Result | None

The parent result node.

property passed: bool

Return the assertion result for the schema node.

In the standard JSON Schema vocabulary, this can only differ from valid for the if keyword: validity may be false (triggering else) while its assertion result is always true.

For the root result node, passed will always equal valid.

path: JSONPointer

The dynamic evaluation path to the current schema node.

relpath: JSONPointer

The path to the current schema node relative to the evaluating (sub)schema.

schema: JSONSchema

The evaluating (sub)schema.

property schema_node: JSON

Return the current schema node.

property valid: bool

Return the validity of the instance against the schema.

validating_with: Metaschema | None

The metaschema being used if this is a JSONSchema.validate() process.