Cerberus Usage

Basic Usage

You define a validation schema and pass it to an instance of the Validator class:

>>> schema = {'name': {'type': 'string'}}
>>> v = Validator(schema)

Then you simply invoke the validate() to validate a dictionary against the schema. If validation succeeds, True is returned:

>>> document = {'name': 'john doe'}
>>> v.validate(document)
True

Alternatively, you can pass both the dictionary and the schema to the validate() method:

>>> v = Validator()
>>> v.validate(document, schema)
True

Which can be handy if your schema is changing through the life of the instance.

Details about validation schemas are covered in Validation Schemas. See Validation Rules and Normalization Rules for an extensive documentation of all supported rules.

Unlike other validation tools, Cerberus will not halt and raise an exception on the first validation issue. The whole document will always be processed, and False will be returned if validation failed. You can then access the errors property to obtain a list of issues. See Errors & Error Handling for different output options.

>>> schema = {'name': {'type': 'string'}, 'age': {'type': 'integer', 'min': 10}}
>>> document = {'name': 'Little Joe', 'age': 5}
>>> v.validate(document, schema)
False
>>> v.errors
{'age': ['min value is 10']}

A DocumentError is raised when the document is not a mapping.

The Validator class and its instances are callable, allowing for the following shorthand syntax:

>>> document = {'name': 'john doe'}
>>> v(document)
True

New in version 0.4.1.

Allowing the Unknown

By default only keys defined in the schema are allowed:

>>> schema = {'name': {'type': 'string', 'maxlength': 10}}
>>> v.validate({'name': 'john', 'sex': 'M'}, schema)
False
>>> v.errors
{'sex': ['unknown field']}

However, you can allow unknown document keys pairs by either setting allow_unknown to True:

>>> v.schema = {}
>>> v.allow_unknown = True
>>> v.validate({'name': 'john', 'sex': 'M'})
True

Or you can set allow_unknown to a validation schema, in which case unknown fields will be validated against it:

>>> v.schema = {}
>>> v.allow_unknown = {'type': 'string'}
>>> v.validate({'an_unknown_field': 'john'})
True
>>> v.validate({'an_unknown_field': 1})
False
>>> v.errors
{'an_unknown_field': ['must be of string type']}

allow_unknown can also be set at initialization:

>>> v = Validator({}, allow_unknown=True)
>>> v.validate({'name': 'john', 'sex': 'M'})
True
>>> v.allow_unknown = False
>>> v.validate({'name': 'john', 'sex': 'M'})
False

allow_unknown can also be set as rule to configure a validator for a nested mapping that is checked against the schema rule:

>>> v = Validator()
>>> v.allow_unknown
False

>>> schema = {
...   'name': {'type': 'string'},
...   'a_dict': {
...     'type': 'dict',
...     'allow_unknown': True,  # this overrides the behaviour for
...     'schema': {             # the validation of this definition
...       'address': {'type': 'string'}
...     }
...   }
... }

>>> v.validate({'name': 'john',
...             'a_dict': {'an_unknown_field': 'is allowed'}},
...            schema)
True

>>> # this fails as allow_unknown is still False for the parent document.
>>> v.validate({'name': 'john',
...             'an_unknown_field': 'is not allowed',
...             'a_dict':{'an_unknown_field': 'is allowed'}},
...            schema)
False

>>> v.errors
{'an_unknown_field': ['unknown field']}

Changed in version 0.9: allow_unknown can also be set for nested dict fields.

Changed in version 0.8: allow_unknown can also be set to a validation schema.

Requiring all

By default any keys defined in the schema are not required. However, you can require all document keys pairs by setting require_all to True at validator initialization (v = Validator(…, require_all=True)) or change it latter via attribute access (v.require_all = True). require_all can also be set as rule to configure a validator for a subdocument that is checked against the schema rule:

>>> v = Validator()
>>> v.require_all
False

>>> schema = {
...   'name': {'type': 'string'},
...   'a_dict': {
...     'type': 'dict',
...     'require_all': True,
...     'schema': {
...       'address': {'type': 'string'}
...     }
...   }
... }

>>> v.validate({'name': 'foo', 'a_dict': {}}, schema)
False
>>> v.errors
{'a_dict': [{'address': ['required field']}]}

>>> v.validate({'a_dict': {'address': 'foobar'}}, schema)
True

New in version 1.3.

Fetching Processed Documents

The normalization and coercion are performed on the copy of the original document and the result document is available via document-property.

>>> v.schema = {'amount': {'type': 'integer', 'coerce': int}}
>>> v.validate({'amount': '1'})
True
>>> v.document
{'amount': 1}

Beside the document-property a Validator-instance has shorthand methods to process a document and fetch its processed result.

validated Method

There’s a wrapper-method validated() that returns the validated document. If the document didn’t validate None is returned, unless you call the method with the keyword argument always_return_document set to True. It can be useful for flows like this:

v = Validator(schema)
valid_documents = [x for x in [v.validated(y) for y in documents]
                   if x is not None]

If a coercion callable or method raises an exception then the exception will be caught and the validation with fail.

New in version 0.9.

normalized Method

Similarly, the normalized() method returns a normalized copy of a document without validating it:

>>> schema = {'amount': {'coerce': int}}
>>> document = {'model': 'consumerism', 'amount': '1'}
>>> normalized_document = v.normalized(document, schema)
>>> type(normalized_document['amount'])
<class 'int'>

New in version 1.0.

Warnings

Warnings, such as about deprecations or likely causes of trouble, are issued through the Python standard library’s warnings module. The logging module can be configured to catch these logging.captureWarnings().