jsonschema.validators
#
Creation and extension of validators, with implementations for existing drafts.
Module Contents#
Classes#
Resolve JSON References. |
Functions#
|
Register the decorated validator for a |
|
Create a new validator class. |
|
Create a new validator class by extending an existing one. |
|
Validate an instance under the given schema. |
|
Retrieve the validator class appropriate for validating the given schema. |
Attributes#
- jsonschema.validators.validates(version)[source]#
Register the decorated validator for a
version
of the specification.Registered validators and their meta schemas will be considered when parsing $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:
- jsonschema.validators.create(meta_schema, validators=(), version=None, type_checker=_types.draft202012_type_checker, format_checker=_format.draft202012_format_checker, id_of=_id_of, applicable_validators=methodcaller('items'))[source]#
Create a new validator class.
- Parameters:
meta_schema (collections.abc.Mapping) – the meta schema for the new validator class
validators (collections.abc.Mapping) –
a mapping from names to callables, where each callable will validate the schema property with the given name.
Each callable should take 4 arguments:
a validator instance,
the value of the property being validated within the instance
the instance
the schema
version (str) – 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 havejsonschema.validators.validates
automatically called for the given version.type_checker (jsonschema.TypeChecker) –
a type checker, used when applying the type keyword.
If unprovided, a
jsonschema.TypeChecker
will be created with a set of default types typical of JSON Schema drafts.format_checker (jsonschema.FormatChecker) –
a format checker, used when applying the format keyword.
If unprovided, a
jsonschema.FormatChecker
will be created with a set of default formats typical of JSON Schema drafts.id_of (collections.abc.Callable) – A function that given a schema, returns its ID.
applicable_validators (collections.abc.Callable) – A function that given a schema, returns the list of applicable validators (validation keywords and callables) which will be used to validate the instance.
- Returns:
a new
jsonschema.protocols.Validator
class
- jsonschema.validators.extend(validator, validators=(), version=None, type_checker=None, format_checker=None)[source]#
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 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 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.
- class jsonschema.validators.RefResolver(base_uri, referrer, store=m(), cache_remote=True, handlers=(), urljoin_cache=None, remote_cache=None)[source]#
Resolve JSON References.
- Parameters:
base_uri (str) – The URI of the referring document
referrer – The actual referring document
store (dict) – A mapping from URIs to documents to cache
cache_remote (bool) – Whether remote refs should be cached after first resolution
handlers (dict) – A mapping from URI schemes to functions that should be used to retrieve them
urljoin_cache (
functools.lru_cache()
) – A cache that will be used for caching the results of joining the resolution scope to subscopes.remote_cache (
functools.lru_cache()
) – A cache that will be used for caching the results of resolved remote URLs.
- classmethod from_schema(schema, id_of=_id_of, *args, **kwargs)[source]#
Construct a resolver from a JSON schema object.
- Parameters:
schema – the referring schema
- Returns:
- push_scope(scope)[source]#
Enter a given sub-scope.
Treats further dereferences as being performed underneath the given scope.
- pop_scope()[source]#
Exit the most recent entered scope.
Treats further dereferences as being performed underneath the original scope.
Don’t call this method more times than
push_scope
has been called.
- in_scope(scope)[source]#
Temporarily enter the given scope for the duration of the context.
Deprecated since version v4.0.0.
- resolving(ref)[source]#
Resolve the given
ref
and enter its resolution scope.Exits the scope on exit of this context manager.
- Parameters:
ref (str) – The reference to resolve
- resolve_fragment(document, fragment)[source]#
Resolve a
fragment
within the referenceddocument
.- Parameters:
document – The referent document
fragment (str) – a URI fragment to resolve within it
- resolve_remote(uri)[source]#
Resolve a remote
uri
.If called directly, does not check the store first, but after retrieving the document at the specified URI it will be saved in the store if
cache_remote
is True.Note
If the requests library is present,
jsonschema
will use it to request the remoteuri
, so that the correct encoding is detected and used.If it isn’t, or if the scheme of the
uri
is nothttp
orhttps
, UTF-8 is assumed.- Parameters:
uri (str) – The URI to resolve
- Returns:
The retrieved document
- jsonschema.validators.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.Draft20212Validator.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:
jsonschema.exceptions.ValidationError – if the instance is invalid
jsonschema.exceptions.SchemaError – if the schema itself is invalid
Footnotes
- jsonschema.validators.validator_for(schema, default=_UNSET)[source]#
Retrieve the validator class appropriate for validating the given schema.
Uses the $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.