API Documentation

Validator Class

class cerberus.Validator(*args, **kwargs)

Validator class. Normalizes and/or validates any mapping against a validation-schema which is provided as an argument at class instantiation or upon calling the validate(), validated() or normalized() method. An instance itself is callable and executes a validation.

All instantiation parameters are optional.

There are the introspective properties types, validators, coercers, default_setters, rules, normalization_rules and validation_rules.

The attributes reflecting the available rules are assembled considering constraints that are defined in the docstrings of rules’ methods and is effectively used as validation schema for schema.


Creates and adds one or multiple errors.


Accepts different argument’s signatures.

1. Bulk addition of errors:

The errors will be added to _errors.

2. Custom error:

  • the invalid field’s name
  • the error message

A custom error containing the message will be created and added to _errors. There will however be fewer information contained in the error (no reference to the violated rule and its constraint).

3. Defined error:

  • the invalid field’s name
  • the error-reference, see cerberus.errors
  • arbitrary, supplemental information about the error

A ValidationError instance will be created and added to _errors.

_errors = None

The list of errors that were encountered since the last document processing was invoked. Type: ErrorList

_get_child_validator(document_crumb=None, schema_crumb=None, **kwargs)
Creates a new instance of Validator-(sub-)class. All initial
parameters of the parent are passed to the initialization, unless a parameter is given as an explicit keyword-parameter.
  • document_crumb (tuple or hashable) – Extends the document_path of the child-validator.
  • schema_crumb (tuple or hashable) – Extends the schema_path of the child-validator.
  • kwargs (dict) – Overriding keyword-arguments for initialization.

an instance of self.__class__

_valid_schemas = set([])

A set of hashed validation schemas that are legit for a particular Validator class.


If True unknown fields that are not defined in the schema will be ignored. If a mapping with a validation schema is given, any undefined field will be validated against its rules. Also see Allowing the Unknown. Type: bool or any mapping


Purge the cache of known valid schemas.

document = None

The document that is or was recently processed. Type: any mapping

document_error_tree = None

A tree representiation of encountered errors following the structure of the document. Type: DocumentErrorTree

document_path = None

The path within the document to the current sub-document. Type: tuple

error_handler = None

The error handler used to format errors and process submitted errors with _error(). Type: BaseErrorHandler


The errors of the last processing formatted by the handler that is bound to error_handler.


Whether to not process None-values in a document or not. Type: bool


True for child-validators obtained with _get_child_validator(). Type: bool

mandatory_validations = ('nullable',)

Rules that are evaluated on any field, regardless whether defined in the schema or not. Type: tuple

normalized(document, schema=None, always_return_document=False)

Returns the document normalized according to the specified rules of a schema.

  • document (any mapping) – The document to normalize.
  • schema (any mapping) – The validation schema. Defaults to None. If not provided here, the schema must have been provided at class instantiation.
  • always_return_document (bool) – Return the document, even if an error occurred. Defaults to: False.

A normalized copy of the provided mapping or None if an error occurred during normalization.

priority_validations = ('nullable', 'readonly', 'type')

Rules that will be processed in that order before any other and abort validation of a document’s field if return True. Type: tuple


If True unknown fields will be deleted from the document unless a validation is called with disabled normalization. Also see Purging Unknown Fields. Type: bool

recent_error = None

The last individual error that was submitted. Type: ValidationError


The allow_unknown attribute of the first level ancestor of a child validator.


The document attribute of the first level ancestor of a child validator.


The schema attribute of the first level ancestor of a child validator.


The registry that holds referenced rules sets. Type: Registry


The validation schema of a validator. When a schema is passed to a method, it replaces this attribute. Type: any mapping or None

schema_error_tree = None

A tree representiation of encountered errors following the structure of the schema. Type: SchemaErrorTree

schema_path = None

The path within the schema to the current sub-schema. Type: tuple


The registry that holds referenced schemas. Type: Registry

validate(document, schema=None, update=False, normalize=True)

Normalizes and validates a mapping against a validation-schema of defined rules.

  • document (any mapping) – The document to normalize.
  • schema (any mapping) – The validation schema. Defaults to None. If not provided here, the schema must have been provided at class instantiation.
  • update (bool) – If True, required fields won’t be checked.
  • normalize (bool) – If True, normalize the document before validation.

True if validation succeeds, otherwise False. Check the errors() property for a list of processing errors.

Return type:


validated(*args, **kwargs)

Wrapper around validate() that returns the normalized and validated document or None if validation failed.

Rules Set & Schema Registry

class cerberus.Registry(definitions={})

A registry to store and retrieve schemas and parts of it by a name that can be used in validation schemas.

Parameters:definitions (any mapping) – Optional, initial defintions.
add(name, definition)

Register a definition to the registry. Existing defintions are replaced silently.

  • name (str) – The name which can be used as reference in a validation schema.
  • definition (any mapping) – The definition.

Returns a dict with all registered definitions mapped to their name.


Purge all defintions in the registry.


Add several defintions at once. Existing defintions are replaced silently.

Parameters:definitions (a mapping or an iterable with two-value tuple s) – The names and defintions.
get(name, default=None)

Retrieve a defintion from the registry.

  • name (str) – The reference that points to the defintion.
  • default – Return value if the reference isn’t registered.

Unregister definitions from the registry.

Parameters:names – The names of the defintions that are to be unregistered.

Error Handlers

class cerberus.errors.BaseErrorHandler(*args, **kwargs)

Base class for all error handlers. Subclasses are identified as error-handlers with an instance-test.


Returns errors in a handler-specific format.

Parameters:errors (iterable of ValidationError instances or a Validator instance) – An object containing the errors.
__init__(*args, **kwargs)

Optionally initialize a new instance.


Be a superhero and implement an iterator over errors.


Add an error to the errors’ container object of a handler.

Parameters:error (ValidationError) – The error to add.
Optionally emits an error in the handler’s format to a stream.
Or light a LED, or even shut down a power plant.
Parameters:error (ValidationError) – The error to emit.

Gets called when a validation ends.

Parameters:validator (Validator) – The calling validator.

Adds all errors to the handler’s container object.

Parameters:errors (iterable of ValidationError instances) – The errors to add.

Gets called when a validation starts.

Parameters:validator (Validator) – The calling validator.
class cerberus.errors.BasicErrorHandler(tree=None)

Models cerberus’ legacy. Returns a dict.

Python Error Representations

class cerberus.errors.ValidationError(document_path, schema_path, code, rule, constraint, value, info)

A simple class to store and query basic error information.


A list that contains the individual errors of a bulk validation error.

code = None

The error’s identifier code. Type: int

constraint = None

The constraint that failed.


Dictionary with errors of an *of-rule mapped to the index of the definition it occurred in. Returns None if not applicable.

document_path = None

The path to the field within the document that caused the error. Type: tuple


Field of the contextual mapping, possibly None.

info = None

May hold additional information about the error. Type: tuple


True for errors of bulk validations.


True for validation errors against different schemas with *of-rules.


True for normalization errors.

rule = None

The rule that failed. Type: string

schema_path = None

The path to the rule within the schema that caused the error. Type: tuple

value = None

The value that failed.

Error Codes

These errors are used as code.

class cerberus.errors.ErrorList

A list for ValidationError instances that can be queried with the in keyword for a particular error code.

class cerberus.errors.ErrorTree(errors=[])

Base class for DocumentErrorTree and SchemaErrorTree.


Add an error to the tree.


Returns all errors for a particular path.

Parameters:pathtuple of hashable s.
Return type:ErrorList

Returns a node for a path.

Parameters:path – Tuple of hashable s.
Return type:ErrorTreeNode or None
class cerberus.errors.DocumentErrorTree(errors=[])

Implements a dict-like class to query errors by indexes following the structure of a validated document.

class cerberus.errors.SchemaErrorTree(errors=[])

Implements a dict-like class to query errors by indexes following the structure of the used schema.


exception cerberus.SchemaError

Raised when the validation schema is missing, has the wrong format or contains errors.

exception cerberus.DocumentError

Raised when the target document is missing or has the wrong format


cerberus.utils.validator_factory(name, mixin=None, class_dict={})
Dynamically create a Validator subclass.
Docstrings of mixin-classes will be added to the resulting class’ one if __doc__ is not in class_dict.
  • name (str) – The name of the new class.
  • mixin (tuple of or a single class) – Class(es) with mixin-methods.
  • class_dict (dict) – Attributes for the new class.

The created class.

Schema Validation Schema

Against this schema validation schemas given to a vanilla Validator will be validated: