API Reference#

Submodules#

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.

class jsonschema.FormatChecker(formats: Iterable[str] | None = None)[source]#

A format property checker.

JSON Schema does not mandate that the format property actually do any validation. If validation is desired however, instances of this class can be hooked into validators to enable format validation.

FormatChecker objects always return True when asked about formats that they do not know how to validate.

To add a check for a custom format use the FormatChecker.checks decorator.

Parameters:

formats – The known formats to validate. This argument can be used to limit which formats will be used during validation.

check(instance: object, format: str) None[source]#

Check whether the instance conforms to the given format.

Parameters:
  • instance (any primitive type, i.e. str, number, bool) – The instance to check

  • format – The format that instance should conform to

Raises:

FormatError – if the instance does not conform to format

checks(format: str, raises: Type[Exception] | Tuple[Type[Exception], ...] = ()) Callable[[_F], _F][source]#

Register a decorated function as validating a new format.

Parameters:
  • format – The format that the decorated function will check.

  • raises

    The exception(s) raised by the decorated function when an invalid instance is found.

    The exception object will be accessible as the jsonschema.exceptions.ValidationError.cause attribute of the resulting validation error.

conforms(instance: object, format: str) bool[source]#

Check whether the instance conforms to the given format.

Parameters:
  • instance (any primitive type, i.e. str, number, bool) – The instance to check

  • format – The format that instance should conform to

Returns:

whether it conformed

Return type:

bool

exception jsonschema.SchemaError(message: str, 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.

class jsonschema.TypeChecker(type_checkers: Mapping[str, Callable[[TypeChecker, Any], bool]] = HashTrieMap({}))[source]#

A type property checker.

A TypeChecker performs type checking for a Validator, converting between the defined JSON Schema types and some associated Python types or objects.

Modifying the behavior just mentioned by redefining which Python objects are considered to be of which JSON Schema types can be done using TypeChecker.redefine or TypeChecker.redefine_many, and types can be removed via TypeChecker.remove. Each of these return a new TypeChecker.

Parameters:

type_checkers – The initial mapping of types to their checking functions.

is_type(instance, type: str) bool[source]#

Check if the instance is of the appropriate type.

Parameters:
  • instance – The instance to check

  • type – The name of the type that is expected.

Raises:

jsonschema.exceptions.UndefinedTypeCheck – if type is unknown to this object.

redefine(type: str, fn) TypeChecker[source]#

Produce a new checker with the given type redefined.

Parameters:
  • type – The name of the type to check.

  • fn (collections.abc.Callable) – A callable taking exactly two parameters - the type checker calling the function and the instance to check. The function should return true if instance is of this type and false otherwise.

redefine_many(definitions=()) TypeChecker[source]#

Produce a new checker with the given types redefined.

Parameters:

definitions (dict) – A dictionary mapping types to their checking functions.

remove(*types) TypeChecker[source]#

Produce a new checker with the given types forgotten.

Parameters:

types – the names of the types to remove.

Raises:

jsonschema.exceptions.UndefinedTypeCheck – if any given type is unknown to this object

jsonschema.validate(instance, schema, cls=None, *args, **kwargs)[source]#

Validate an instance under the given schema.

>>> validate([2, 3, 4], {"maxItems": 2})
Traceback (most recent call last):
    ...
ValidationError: [2, 3, 4] is too long

validate() will first verify that the provided schema is itself valid, since not doing so can lead to less obvious error messages and fail in less obvious or consistent ways.

If you know you have a valid schema already, especially if you intend to validate multiple instances with the same schema, you likely would prefer using the jsonschema.protocols.Validator.validate method directly on a specific validator (e.g. Draft202012Validator.validate).

Parameters:
  • instance – The instance to validate

  • schema – The schema to validate with

  • cls (jsonschema.protocols.Validator) – The class that will be used to validate the instance.

If the cls argument is not provided, two things will happen in accordance with the specification. First, if the schema has a $schema keyword containing a known meta-schema [1] then the proper validator will be used. The specification recommends that all schemas contain $schema properties for this reason. If no $schema property is found, the default validator class is the latest released draft.

Any other provided positional and keyword arguments will be passed on when instantiating the cls.

Raises:

Footnotes

jsonschema._format._F = ~_F#

A format checker callable.

jsonschema._typing.id_of#

alias of Callable[[Union[bool, Mapping[str, Any]]], Optional[str]]