schemmy

Validate data with plain type annotations. No dependencies.

pip install schemmy
# or
uv add schemmy

Requires Python 3.12+.

Example

from typing import Annotated

from schemmy import Schema, ValidationError


def positive(value: int) -> int:
    if value <= 0:
        raise ValueError("must be greater than zero")
    return value


class Item(Schema):
    sku: str
    qty: Annotated[int, positive]


class Order(Schema):
    id: int
    items: list[Item]


order = Order.validate({"id": 1, "items": [{"sku": "A1", "qty": 2}]})
order.items[0].qty  # 2

All errors are collected at once, not just the first one. Each error carries the path to the field:

try:
    Order.validate({"id": "1", "items": [{"sku": "A1", "qty": 0}, {"qty": 3}], "note": "x"})
except ValidationError as exc:
    for error in exc.exceptions:
        print(error.location, error.message)

['note'] Unknown field
['id'] Expected int, got str
['items', 0, 'qty'] Validator positive failed: must be greater than zero
['items', 1, 'sku'] Field required

Errors come in a stable order: missing and unknown fields first, then value errors in field declaration order.

ValidationError is an ExceptionGroup of FieldValidationError, so except* FieldValidationError works too. Both errors can be pickled and copied.

What is supported

A validator is a callable that takes a value and returns it, possibly changed. To report an error, a validator raises an exception. The first failing validator stops the chain. The returned value is stored in the schema, so validators can normalize data, for example bring a phone number to a single format.

Unknown fields and missing required fields are validation errors as well. Input to Schema.validate that is not a dict produces a single error with an empty location. Input to a recursive schema nested deeper than the Python recursion limit allows produces a single Maximum nesting depth exceeded error.

A field with a default value is optional. If the field is not passed, the schema gets a copy of the default. The default value itself is not validated.

ClassVar annotations are not fields.

Bare typing.List, typing.Dict and typing.Tuple are treated as list[Any], dict[Any, Any] and tuple[Any, ...].

Working with instances

order.to_dict()
# {'id': 1, 'items': [{'sku': 'A1', 'qty': 2}]}

order
# Order(id=1, items=[Item(sku='A1', qty=2)])

Order.validate(order.to_dict()) == order
# True

to_dict converts nested schemas recursively and keeps field declaration order. Schemas compare by class and field values. Schemas are mutable and therefore unhashable.

Type checking

Type checkers derive the constructor signature from the annotations, so wrong types, unknown and missing fields are reported before runtime:

Item(sku=1, qty=2)  # error: expected str
Item(sku="A1", qyt=2)  # error: unknown argument

The constructor is typed for already typed values. Use Schema.validate for raw data such as parsed JSON, where nested schemas arrive as dicts.

Limitations

set, frozenset, TypedDict and other annotations not listed above are not supported yet. A field with such an annotation produces an "unsupported type" error.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run ty check

License

MIT