Creating or Extending Validator Classes

jsonschema.validators.create(meta_schema: ~collections.abc.Mapping[str, ~typing.Any], validators: ~collections.abc.Mapping[str, ~jsonschema._typing.SchemaKeywordValidator] | ~collections.abc.Iterable[tuple[str, ~jsonschema._typing.SchemaKeywordValidator]] = (), version: str | None = None, type_checker: ~jsonschema._types.TypeChecker = <TypeChecker types={'array', 'boolean', 'integer', 'null', 'number', 'object', 'string'}>, format_checker: ~jsonschema._format.FormatChecker = <FormatChecker checkers=['date', 'email', 'idn-email', 'idn-hostname', 'ipv4', 'ipv6', 'iri', 'iri-reference', 'json-pointer', 'regex', 'relative-json-pointer', 'uri', 'uri-reference', 'uuid']>, id_of: ~typing.Callable[[bool | ~collections.abc.Mapping[str, ~typing.Any]], str | None] = <function _dollar_id>, applicable_validators: ~typing.Callable[[bool | ~collections.abc.Mapping[str, ~typing.Any]], ~typing.Iterable[~typing.Tuple[str, ~typing.Any]]] = operator.methodcaller('items'))

Create a new validator class.

Parameters:

• meta_schema – the meta schema for the new validator class

• validators –

  a mapping from names to callables, where each callable will validate the schema property with the given name.

  Each callable should take 4 arguments:

  1. a validator instance,

  2. the value of the property being validated within the instance

  3. the instance

  4. the schema

• version – an identifier for the version that this validator class will validate. If provided, the returned validator class will have its __name__ set to include the version, and also will have jsonschema.validators.validates automatically called for the given version.

• type_checker –

  a type checker, used when applying the :kw:`type` keyword.

  If unprovided, a jsonschema.TypeChecker will be created with a set of default types typical of JSON Schema drafts.

• format_checker –

  a format checker, used when applying the :kw:`format` keyword.

  If unprovided, a jsonschema.FormatChecker will be created with a set of default formats typical of JSON Schema drafts.

• id_of – A function that given a schema, returns its ID.

• applicable_validators – A function that, given a schema, returns the list of applicable schema keywords and associated values which will be used to validate the instance. This is mostly used to support pre-draft 7 versions of JSON Schema which specified behavior around ignoring keywords if they were siblings of a $ref keyword. If you’re not attempting to implement similar behavior, you can typically ignore this argument and leave it at its default.

Returns:

a new jsonschema.protocols.Validator class

jsonschema.validators.extend(validator, validators=(), version=None, type_checker=None, format_checker=None)

Create a new validator class by extending an existing one.

Parameters:

• validator (jsonschema.protocols.Validator) – an existing validator class

• validators (collections.abc.Mapping) –

  a mapping of new validator callables to extend with, whose structure is as in create.

  Note

  Any validator callables with the same name as an existing one will (silently) replace the old validator callable entirely, effectively overriding any validation done in the “parent” validator class.

  If you wish to instead extend the behavior of a parent’s validator callable, delegate and call it directly in the new validator function by retrieving it using OldValidator.VALIDATORS["validation_keyword_name"].

• version (str) – a version for the new validator class

• type_checker (jsonschema.TypeChecker) –

  a type checker, used when applying the :kw:`type` keyword.

  If unprovided, the type checker of the extended jsonschema.protocols.Validator will be carried along.

• format_checker (jsonschema.FormatChecker) –

  a format checker, used when applying the :kw:`format` keyword.

  If unprovided, the format checker of the extended jsonschema.protocols.Validator will be carried along.

Returns:

a new jsonschema.protocols.Validator class extending the one provided

Note

Meta Schemas

The new validator class will have its parent’s meta schema.

If you wish to change or extend the meta schema in the new validator class, modify META_SCHEMA directly on the returned class. Note that no implicit copying is done, so a copy should likely be made before modifying it, in order to not affect the old validator.

jsonschema.validators.validator_for(schema, default=<unset>)

Retrieve the validator class appropriate for validating the given schema.

Uses the :kw:`$schema` keyword that should be present in the given schema to look up the appropriate validator class.

Parameters:

• schema (collections.abc.Mapping or bool) – the schema to look at

• default –

  the default to return if the appropriate validator class cannot be determined.

  If unprovided, the default is to return the latest supported draft.

Examples

The :kw:`$schema` JSON Schema keyword will control which validator class is returned:

>>> schema = {
...     "$schema": "https://json-schema.org/draft/2020-12/schema",
...     "type": "integer",
... }
>>> jsonschema.validators.validator_for(schema)
<class 'jsonschema.validators.Draft202012Validator'>

Here, a draft 7 schema instead will return the draft 7 validator:

>>> schema = {
...     "$schema": "http://json-schema.org/draft-07/schema#",
...     "type": "integer",
... }
>>> jsonschema.validators.validator_for(schema)
<class 'jsonschema.validators.Draft7Validator'>

Schemas with no $schema keyword will fallback to the default argument:

>>> schema = {"type": "integer"}
>>> jsonschema.validators.validator_for(
...     schema, default=Draft7Validator,
... )
<class 'jsonschema.validators.Draft7Validator'>

or if none is provided, to the latest version supported. Always including the keyword when authoring schemas is highly recommended.

jsonschema.validators.validates(version)

Register the decorated validator for a version of the specification.

Registered validators and their meta schemas will be considered when parsing :kw:`$schema` keywords’ URIs.

Parameters:

version (str) – An identifier to use as the version’s name

Returns:

a class decorator to decorate the validator with the version

Return type:

collections.abc.Callable

Creating Validation Errors

Any validating function that validates against a subschema should call descend, rather than iter_errors. If it recurses into the instance, or schema, it should pass one or both of the path or schema_path arguments to descend in order to properly maintain where in the instance or schema respectively the error occurred.

The Validator Protocol

jsonschema defines a protocol, jsonschema.protocols.Validator which can be used in type annotations to describe the type of a validator.

For full details, see The Validator Protocol.