jtd package

Subpackages

Submodules

jtd.schema module

class jtd.schema.Form

Bases: enum.Enum

Represents the “forms” a JSON Typedef schema can take on. The JSON Typedef spec restricts valid schemas to only using certain combinations of keywords. This enum represents which of those valid combinations a schema is using.

DISCRIMINATOR = 8

ELEMENTS = 5

EMPTY = 1

ENUM = 4

PROPERTIES = 6

REF = 2

TYPE = 3

VALUES = 7

class jtd.schema.Schema(metadata: Optional[Dict[str, Any]], nullable: Optional[bool], definitions: Optional[Dict[str, Schema]], ref: Optional[str], type: Optional[str], enum: Optional[List[str]], elements: Optional[Schema], properties: Optional[Dict[str, Schema]], optional_properties: Optional[Dict[str, Schema]], additional_properties: Optional[bool], values: Optional[Schema], discriminator: Optional[str], mapping: Optional[Dict[str, Schema]])

Bases: object

Represents a JSON Typedef schema. To construct an instance of Schema, it’s recommended you use from_dict().

>>> import jtd
>>> schema = jtd.Schema.from_dict({ 'elements': { 'type': 'string' }})
>>> schema.form()
<Form.ELEMENTS: 5>
>>> schema.elements.form()
<Form.TYPE: 3>

additional_properties = None

Describes whether there may be properties not in properties or optional_properties.

definitions = None

A set of definitions that ref can refer to. Can only appear on root schemas.

discriminator = None

Specifies the “tag” property of an object, indicating what kind of data it contains.

elements = None

Describes arrays.

enum = None

Describes data that must be in a predefined list of strings.

form() → jtd.schema.Form

Determine the form of the schema. Meaningful only if validate() did not throw any exceptions.

>>> import jtd
>>> jtd.Schema.from_dict({}).form()
<Form.EMPTY: 1>
>>> jtd.Schema.from_dict({ 'enum': ['foo', 'bar' ]}).form()
<Form.ENUM: 4>
>>> jtd.Schema.from_dict({ 'elements': {} }).form()
<Form.ELEMENTS: 5>

classmethod from_dict(dict: Dict[str, Any]) → jtd.schema.Schema

Instantiate a Schema from a dictionary. The dictionary should only contain types produced by json.loads; otherwise, the output is not meaningful.

>>> import jtd
>>> jtd.Schema.from_dict({ 'elements': { 'type': 'string' }})
Schema(metadata=None, nullable=None, definitions=None, ref=None, type=None, enum=None, elements=Schema(metadata=None, nullable=None, definitions=None, ref=None, type='string', enum=None, elements=None, properties=None, optional_properties=None, additional_properties=None, values=None, discriminator=None, mapping=None), properties=None, optional_properties=None, additional_properties=None, values=None, discriminator=None, mapping=None)

mapping = None

Describes the data, depending on the value of the “tag” property of an object.

metadata = None

Additional metadata. Does not affect validation.

nullable = None

Describes data that can be JSON null (Python None).

optional_properties = None

Describes optional properties of an object.

properties = None

Describes required properties of an object.

ref = None

A reference to a definition.

type = None

Describes data that is a boolean, number, string, or timestamp.

validate(root=None)

Checks whether a schema satisfies the semantic rules of JSON Typedef, such as ensuring that all refs have a corresponding definition.

>>> import jtd
>>> schema = jtd.Schema.from_dict({ 'ref': 'xxx' })
>>> schema.validate()
Traceback (most recent call last):
    ...
TypeError: ref but no definitions

values = None

Describes the values of an object.

jtd.validate module

exception jtd.validate.MaxDepthExceededError

Bases: Exception

Indicates that ref recursion depth exceeded the limit put in place by max_depth in ValidationOptions.

class jtd.validate.ValidationError(instance_path: List[str], schema_path: List[str])

Bases: object

Represents a single issue that a schema had with an instance.

instance_path = None

Path to the part of the instance that was rejected.

schema_path = None

Path to the part of the schema that did the rejecting.

class jtd.validate.ValidationOptions(max_depth: int = 0, max_errors: int = 0)

Bases: object

Represents options that can be passed to validate().

max_depth = 0

The maximum number of refs that will be followed at once before raising MaxDepthExceededError.

A value of zero means that all refs will be followed, and MaxDepthExceededError is never raised. Ultimately, stack overflow may cause an error instead.

max_errors = 0

The maximum number of errors that will be returned.

A value of zero means that all errors will be returned.

jtd.validate.validate(**kwargs) → List[jtd.validate.ValidationError]

Performs JSON Typedef validation, and returns a list of validation errors.

Provide the schema using the schema keyword argument, and the instance with the instance keyword argument. Optionally, you can pass ValidationOptions with the options keyword argument.

>>> import jtd
>>> schema = jtd.Schema.from_dict({ 'type': 'string' })
>>> jtd.validate(schema=schema, instance="foo")
[]
>>> jtd.validate(schema=schema, instance=None)
[ValidationError(instance_path=[], schema_path=['type'])]

>>> import jtd
>>> schema = jtd.Schema.from_dict({ 'elements': { 'type': 'string' }})
>>> len(jtd.validate(schema=schema, instance=[None] * 5))
5
>>> options = jtd.ValidationOptions(max_errors=3)
>>> len(jtd.validate(schema=schema, instance=[None] * 5, options=options))
3

>>> import jtd
>>> schema = { 'definitions': { 'loop': { 'ref': 'loop' }}, 'ref': 'loop' }
>>> schema = jtd.Schema.from_dict(schema)
>>> options = jtd.ValidationOptions(max_depth=32)
>>> jtd.validate(schema=schema, instance=None, options=options)
Traceback (most recent call last):
    ...
MaxDepthExceededError

Module contents