92 lines
3.3 KiB
ReStructuredText
92 lines
3.3 KiB
ReStructuredText
.. _creating-validators:
|
|
|
|
================================
|
|
Creating or Extending Validators
|
|
================================
|
|
|
|
.. currentmodule:: jsonschema.validators
|
|
|
|
.. autofunction:: create
|
|
|
|
Create a new validator (class).
|
|
|
|
:argument dict meta_schema: the meta schema for the new validator class
|
|
|
|
:argument dict validators: a mapping from validator names to functions that
|
|
validate the given name. Each function should take 4 arguments: a
|
|
validator instance, the value of the current validator property in the
|
|
instance being validated, the instance, and the schema.
|
|
|
|
:argument str version: an identifier for the version that this validator
|
|
will validate. If provided, the returned validator class will have its
|
|
``__name__`` set to include the version, and also will have
|
|
:func:`validates` automatically called for the given version.
|
|
|
|
:argument dict default_types: a default mapping to use for instances of the
|
|
validator when mapping between JSON types to Python types. The default
|
|
for this argument is probably fine. Instances of the returned validator
|
|
can still have their types customized on a per-instance basis.
|
|
|
|
:returns: a new :class:`jsonschema.IValidator` class
|
|
|
|
|
|
.. autofunction:: extend
|
|
|
|
Create a new validator that extends an existing validator class.
|
|
|
|
:argument jsonschema.IValidator validator: an existing validator class
|
|
|
|
:argument dict validators: a set of new validators to add to the new
|
|
validator.
|
|
|
|
.. note::
|
|
|
|
Any validators with the same name as an existing one will
|
|
(silently) replace the old validator entirely.
|
|
|
|
If you wish to extend an old validator, call it directly in the
|
|
replacing validator function by retrieving it using
|
|
``OldValidator.VALIDATORS["the validator"]``.
|
|
|
|
:argument str version: a version for the new validator
|
|
|
|
:returns: a new :class:`jsonschema.IValidator` class
|
|
|
|
.. note:: Meta Schemas
|
|
|
|
The new validator will just keep the old validator's meta schema.
|
|
|
|
If you wish to change or extend the meta schema in the new validator,
|
|
modify ``META_SCHEMA`` directly on the returned class.
|
|
|
|
The meta schema on the new validator will not be a copy, so you'll
|
|
probably want to copy it before modifying it to not affect the old
|
|
validator.
|
|
|
|
|
|
.. autofunction:: validator_for
|
|
|
|
Retrieve the validator appropriate for validating the given schema.
|
|
|
|
Uses the :validator:`$schema` property that should be present in the given
|
|
schema to look up the appropriate validator.
|
|
|
|
:argument schema: the schema to look at
|
|
:argument default: the default to return if the appropriate validator
|
|
cannot be determined. If unprovided, the default will be to just return
|
|
:class:`Draft4Validator`
|
|
|
|
|
|
.. autofunction:: validates
|
|
|
|
|
|
Creating Validation Errors
|
|
--------------------------
|
|
|
|
Any validating function that validates against a subschema should call
|
|
:meth:`ValidatorMixin.descend`, rather than :meth:`ValidatorMixin.iter_errors`.
|
|
If it recurses into the instance, or schema, it should pass one or both of the
|
|
``path`` or ``schema_path`` arguments to :meth:`ValidatorMixin.descend` in
|
|
order to properly maintain where in the instance or schema respsectively the
|
|
error occurred.
|