Cerberus: Lightweight Schema Validator

1.3.8 · active · verified Thu Apr 09

Cerberus is a lightweight, extensible data validation library for Python dictionaries. It allows you to define a schema and then validate whether a given dictionary conforms to that schema, supporting various data types, constraints, and custom validation rules. The current version is 1.3.8, and it maintains a stable release cadence with incremental updates within the 1.x series.

Warnings

breaking Starting with Cerberus 1.3.0, the `allow_unknown` validator option (which controls whether unknown fields in a document are allowed) now defaults to `False`. Previously, it implicitly allowed unknown fields.
Fix: If your application relies on unknown fields being allowed, explicitly set `allow_unknown=True` when initializing the `Validator` (`v = Validator(schema, allow_unknown=True)`) or define `allow_unknown: True` in relevant schema rules.
gotcha Since Cerberus 1.1, `type` schema rules are processed *before* `coerce` rules. This means type validation is performed on the original value, not the coerced value.
Fix: Be aware of this order. If your intent is to validate the type *after* coercion, ensure your `coerce` rule correctly handles the initial type, or apply type validation in a custom rule that runs post-coercion if necessary.
gotcha The `required: True` and `nullable: True` schema rules are orthogonal. `required: True` means the key *must* exist in the document. `nullable: True` means that if the key exists, its value *can* be `None`.
Fix: Understand the distinction: `{'field': {'required': True, 'nullable': False}}` requires the field and its value cannot be `None`. `{'field': {'required': False, 'nullable': True}}` makes the field optional, but if present, its value can be `None`.

Install

pip install cerberus Install Cerberus

Imports

Validator
```
from cerberus import Validator
```

Quickstart

This quickstart demonstrates defining a schema with various rules (type, length, required, regex, min/max, nullable). It then creates a Validator instance, validates a sample document, and prints success or error messages. It also includes an example of an invalid document to show error reporting.

from cerberus import Validator

schema = {
    'name': {'type': 'string', 'minlength': 3, 'maxlength': 10, 'required': True},
    'age': {'type': 'integer', 'min': 0, 'max': 99, 'nullable': True},
    'email': {'type': 'string', 'regex': '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'}
}

document = {
    'name': 'John Doe',
    'age': 30,
    'email': 'john.doe@example.com'
}

v = Validator(schema)

if v.validate(document):
    print('Document is valid.')
    print(f'Normalized document: {v.normalized(document)}')
else:
    print('Document is invalid.')
    print(f'Errors: {v.errors}')

# Example with an invalid document
invalid_document = {
    'name': 'Jo',
    'age': 150,
    'city': 'New York' # Unknown field
}

if not v.validate(invalid_document):
    print(f'Invalid document errors: {v.errors}')

view raw JSON →