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.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.