jschon.jsonformat

exception jschon.jsonformat.JSONFormatError

Error originating from the jschon.jsonformat module.

exception jschon.jsonformat.MetadocumentClassRequiredError

Raised when no metadocuemnt class can be determined.

class jschon.jsonformat.EvaluableJSON(*args, **kwargs)

Protocol for documents that can evaluate another document.

__init__(*args, **kwargs)
evaluate(instance, result=None)
Parameters:
Return type:

EvaluableJSONResult

initial_validation_result(instance)
Parameters:

instance (JSON) –

Return type:

EvaluableJSONresult

class jschon.jsonformat.EvaluableJSONResult(*args, **kwargs)

Protocol for evaluation results, which (like documents) form a tree.

A result has a boolean validity, and optionally arbitrary additional data. It starts in a state of being valid, with no data. It can be made invalid using fail(), and data can be added with annotate(). In some cases a valid result’s additional data can become irrelevant, which can be indicated using discard().

The additional result data is reported using output(), which takes a format parameter, the values of which are specific to the type of evaluation being performed.

__call__(instance, schema=None, *, cls)
Parameters:
Return type:

ContextManager[EvaluableJSONResult]

__init__(*args, **kwargs)
annotate(value)

Annotate the result with arbitrary JSON-format data.

Parameters:

value (JSONCompatible) –

Return type:

None

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 (Optional[JSONCompatible]) –

Return type:

None

output(format, **kwargs)

Return the evaluation result in the specified format.

Parameters:

  • format (str) – A string specific to the type of evaluation indicating the output format. It should be registered with the output_formatter() decorator.

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

Return type:

JSONCompatible

property valid: bool

Return the validity of the instance against the schema.

class jschon.jsonformat.JSONFormat(*args, metadocument_uri=None, metadocument_cls=None, **kwargs)
__init__(*args, metadocument_uri=None, metadocument_cls=None, **kwargs)
Parameters:

  • args (Any) –

  • metadocument_uri (Optional[URI]) –

  • metadocument_cls (Optional[Type[EvaluableJSON]]) –

is_format_root()

Indicates this is the root of a format instance within a document.

A node without a format_parent should always return true.

pre_recursion_init(*args, **kwargs)
validate()

Validate the document against its metadocument.

Return type:

EvaluableJSONResult

property format_parent: JSONFormat | None

Returns the nearest ancestor that is a JSONFormat.

This will always be the same JSONFormat subclass as the invoking node, but may cross a format_root; see also parent_in_format to avoid such crossing.

Note that a node can have a parent without necessarily having a format_parent.

property format_root

The most distant ancestor in the same format-document.

In the case of nesting formats such as JSON Schema, the format_root can have a format_parent, but never has a parent_in_format.

property metadocument: EvaluableJSON

A document describing this document and how to process it.

The specifics of what it means to “process” a format can vary considerably, from simply indicating whether it is a valid instance of the format, to selecting the specific semantics of the document within the range permitted by the format (e.g. in JSON Schema, vocabulary selection).

property metadocument_uri: URI | None

The URI of a document that describes this document.

property parent_in_format: JSONFormat | None

Returns the nearest ancestor resource node in the same format.

This skips any intervening ancestor nodes that are not instances of this same format, and does not cross format_root boundaries. It returns None if this node is a format root.