API Documentation

Validator Class

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

Validator class. Validates any Python dict against a validation schema,

which is provided as an argument at class instantiation, or upon calling the validate() method.

Parameters:
  • schema – optional validation schema.
  • transparent_schema_rules – if True unknown schema rules will be ignored (no SchemaError will be raised). Defaults to False. Useful you need to extend the schema grammar beyond Cerberus’ domain.
  • ignore_none_values – If True it will ignore None values for type checking. (no UnknownType error will be added). Defaults to False. Useful if your document is composed from function kwargs with defaults.
  • allow_unknown – if True unknown key/value pairs (not present in the schema) will be ignored, and validation will pass. Defaults to False, returning an ‘unknown field error’ un validation.

Changed in version 0.9.2: only perform shallow copies in order to avoid issues with Python 2.6 way to handle deepcopy on BytesIO (and in general, complex objects). Closes #147.

Changed in version 0.9.1: ‘required’ will always be validated, regardless of any dependencies.

New in version 0.9: ‘anyof’, ‘noneof’, ‘allof’, ‘anyof’ validation rules. PyPy support. ‘coerce’ rule. ‘propertyschema’ validation rule. ‘validator.validated’ takes a document as argument and returns a Validated document or ‘None’ if validation failed.

Changed in version 0.9: Use ‘str.format’ in error messages so if someone wants to override them does not get an excpetion if arguments are not passed. ‘keyschema’ is renamed to ‘valueschema’. Closes #92. ‘type’ can be a list of valid types. Usages of ‘document’ to ‘self.document’ in ‘_validate’. When ‘items’ is applied to a list, field name is used as key for ‘validator.errors’, and offending field indexes are used as keys for Field errors ({‘a_list_of_strings’: {1: ‘not a string’}}) Additional kwargs that are passed to the __init__-method of an Instance of Validator-(sub-)class are passed to child-validators. Ensure that additional **kwargs of a subclass persist through validation Improve failure message when testing against multiple types. Ignore ‘keyschema’ when not a mapping. Ignore ‘schema’ when not a sequence. ‘allow_unknown’ can also be set for nested dicts. Closes #75. Raise SchemaError when an unallowed ‘type’ is used in conjunction with ‘schema’ rule.

Changed in version 0.8.1: ‘dependencies’ for sub-document fields. Closes #64. ‘readonly’ should be validated before any other validation. Closes #63. ‘allow_unknown’ does not apply to sub-dictionaries in a list. Closes #67. update mode does not ignore required fields in subdocuments. Closes #72. ‘allow_unknown’ does not respect custom rules. Closes #66.

New in version 0.8: ‘dependencies’ also support a dict of dependencies. ‘allow_unknown’ can be a schema used to validate unknown fields. Support for function-based validation mode.

Changed in version 0.7.2: Successfully validate int as a float type.

Changed in version 0.7.1: Validator options like ‘allow_unknown’ and ‘ignore_none_values’ are now taken into consideration when validating sub-dictionaries. Make self.document always the root level document. Up-front validation for schemas.

New in version 0.7: ‘keyschema’ validation rule. ‘regex’ validation rule. ‘dependencies’ validation rule. ‘mix’, ‘max’ now apply on floats and numbers too. Closes #30. ‘set’ data type.

New in version 0.6: ‘number’ (integer or float) validator.

Changed in version 0.5.0: validator.errors returns a dict where keys are document fields and values are validation errors.

Changed in version 0.4.0: validate_update() is deprecated. Use validate() with update=True instead. Type validation is always performed first (only exception being nullable). On failure, it blocks other rules on the same field. Closes #18.

New in version 0.2.0: self.errors returns an empty list when validate() has not been called. Option so allow nullable field values. Option to allow unknown key/value pairs.

New in version 0.1.0: Option to ignore None values for type checking.

New in version 0.0.3: Support for transparent schema rules. Added new ‘empty’ rule for string fields.

New in version 0.0.2: Support for addition and validation of custom data types.

current

Get the current document being validated.

When validating, the current (sub)document will be available via this property.

errors
Return type:a list of validation errors. Will be empty if no errors were found during. Resets after each call to validate().
validate(document, schema=None, update=False, context=None)

Validates a Python dictionary against a validation schema.

Parameters:
  • document – the dict to validate.
  • schema – the validation schema. Defaults to None. If not provided here, the schema must have been provided at class instantiation.
  • update – If True validation of required fields won’t be performed.
  • context – the document in which context validation should be performed. Defaults to None.
Returns:

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

Changed in version 0.4.0: Support for update mode.

validate_schema(schema)

Validates a schema against supported rules.

Parameters:schema – the schema to be validated as a legal cerberus schema according to the rules of this Validator object.

New in version 0.7.1.

validate_update(document, schema=None, context=None)

Validates a Python dictionary against a validation schema. The difference with validate() is that the required rule will be ignored here.

Parameters:
  • schema – optional validation schema. Defaults to None. If not provided here, the schema must have been provided at class instantiation.
  • context – the context in which the document should be validated. Defaults to None.
Returns:

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

Deprecated since version 0.4.0: Use validate() with update=True instead.

validated(*args, **kwargs)

Wrapper around Validator.validate that returns the validated document or None if validation failed.

Exceptions

class cerberus.SchemaError

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

class cerberus.ValidationError

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