jsonschema#

An implementation of JSON Schema for Python

The main functionality is provided by the validator classes for each of the supported JSON Schema versions.

Most commonly, jsonschema.validators.validate is the quickest way to simply validate a given instance under a schema, and will create a validator for you.

Submodules#

Package Contents#

Classes#

ErrorTree

ErrorTrees make it easier to check which validations failed.

Validator

The protocol to which all validator classes adhere.

class jsonschema.ErrorTree(errors=())[source]#

ErrorTrees make it easier to check which validations failed.

property total_errors#

The total number of errors in the entire tree, including children.

exception jsonschema.FormatError(message, cause=None)[source]#

Validating a format failed.

exception jsonschema.RefResolutionError[source]#

A ref could not be resolved.

exception jsonschema.SchemaError(message, validator=_unset, path=(), cause=None, context=(), validator_value=_unset, instance=_unset, schema=_unset, schema_path=(), parent=None, type_checker=_unset)[source]#

A schema was invalid under its corresponding metaschema.

exception jsonschema.ValidationError(message, validator=_unset, path=(), cause=None, context=(), validator_value=_unset, instance=_unset, schema=_unset, schema_path=(), parent=None, type_checker=_unset)[source]#

An instance was invalid under a provided schema.

class jsonschema.Validator(schema: Mapping | bool, resolver: jsonschema.RefResolver | None = None, format_checker: jsonschema.FormatChecker | None = None)[source]#

The protocol to which all validator classes adhere.

Parameters:
  • schema – The schema that the validator object will validate with. It is assumed to be valid, and providing an invalid schema can lead to undefined behavior. See Validator.check_schema to validate a schema first.

  • resolver – a resolver that will be used to resolve $ref properties (JSON references). If unprovided, one will be created.

  • format_checker – if provided, a checker which will be used to assert about format properties present in the schema. If unprovided, no format validation is done, and the presence of format within schemas is strictly informational. Certain formats require additional packages to be installed in order to assert against instances. Ensure you’ve installed jsonschema with its extra (optional) dependencies when invoking pip.

Deprecated since version v4.12.0: Subclassing validator classes now explicitly warns this is not part of their public API.

META_SCHEMA :ClassVar[collections.abc.Mapping]#
VALIDATORS :ClassVar[collections.abc.Mapping]#
TYPE_CHECKER :ClassVar[jsonschema.TypeChecker]#
FORMAT_CHECKER :ClassVar[jsonschema.FormatChecker]#
ID_OF :collections.abc.Callable[[Any], str | None]#
schema :Mapping | bool#
classmethod check_schema(schema: Mapping | bool) None#

Validate the given schema against the validator’s META_SCHEMA.

Raises:

jsonschema.exceptions.SchemaError – if the schema is invalid

is_type(instance: Any, type: str) bool#

Check if the instance is of the given (JSON Schema) type.

Parameters:
  • instance – the value to check

  • type – the name of a known (JSON Schema) type

Returns:

whether the instance is of the given type

Raises:

jsonschema.exceptions.UnknownType – if type is not a known type

is_valid(instance: Any) bool#

Check if the instance is valid under the current schema.

Returns:

whether the instance is valid or not

>>> schema = {"maxItems" : 2}
>>> Draft202012Validator(schema).is_valid([2, 3, 4])
False
iter_errors(instance: Any) Iterable[jsonschema.exceptions.ValidationError]#

Lazily yield each of the validation errors in the given instance.

>>> schema = {
...     "type" : "array",
...     "items" : {"enum" : [1, 2, 3]},
...     "maxItems" : 2,
... }
>>> v = Draft202012Validator(schema)
>>> for error in sorted(v.iter_errors([2, 3, 4]), key=str):
...     print(error.message)
4 is not one of [1, 2, 3]
[2, 3, 4] is too long

Deprecated since version v4.0.0: Calling this function with a second schema argument is deprecated. Use Validator.evolve instead.

validate(instance: Any) None#

Check if the instance is valid under the current schema.

Raises:

jsonschema.exceptions.ValidationError – if the instance is invalid

>>> schema = {"maxItems" : 2}
>>> Draft202012Validator(schema).validate([2, 3, 4])
Traceback (most recent call last):
    ...
ValidationError: [2, 3, 4] is too long
evolve(**kwargs) Validator#

Create a new validator like this one, but with given changes.

Preserves all other attributes, so can be used to e.g. create a validator with a different schema but with the same $ref resolution behavior.

>>> validator = Draft202012Validator({})
>>> validator.evolve(schema={"type": "number"})
Draft202012Validator(schema={'type': 'number'}, format_checker=None)

The returned object satisfies the validator protocol, but may not be of the same concrete class! In particular this occurs when a $ref occurs to a schema with a different $schema than this one (i.e. for a different draft).

>>> validator.evolve(
...     schema={"$schema": Draft7Validator.META_SCHEMA["$id"]}
... )
Draft7Validator(schema=..., format_checker=None)