About Probatio

Probatio exists because a huge amount of Python leans on voluptuous for data validation, and voluptuous has gone quiet. The idea is excellent and the API is loved; what it needs is a maintained home. Probatio is that home: the same public API, written fresh, MIT licensed, and actively developed.

voluptuous runs a lot of Python

Home Assistant validates every integration’s configuration with voluptuous. So does a long tail of libraries and tools across the ecosystem. The premise that made it popular is genuinely good: a schema is just data describing data, built from plain Python types, dicts, lists, and small helpers, then called with a value to validate it. You already know the language; the schema is just more of it.

That reach is also the problem. When the library underneath millions of installations stops moving, every consumer inherits the bugs that never get fixed, the sharp edges that never get filed down, and the Python versions that never get supported.

The state of validation in Python

Reaching for validation in Python tends to mean one of a few trades:

• voluptuous is the lightweight, schema-is-data choice that Home Assistant and many others standardized on. The model is compact and easy to compose, but the project has seen little movement for years, and several rough edges (a RecursionError on deep data, a leaked TypeError from a built-in validator, errors reported twice) sit unfixed.
• mashumaro is a fast, dataclass-first take focused on serialization and deserialization. It is excellent at what it does, and several ideas in Probatio are borrowed from it with credit (see the architecture decision records). It is a codec library more than a free-form validator, though, so the schema-is-data model is not the problem it set out to solve.
• pydantic is the heavyweight, framework choice: a BaseModel class that is your schema, type, validator, and serializer at once. It is fast and capable, but it asks you to describe data as pydantic model classes, a different mental model and a migration, not a drop-in. (Probatio also returns typed objects, from your own dataclasses and TypedDicts, without a base class; the comparison page draws the line.) It has also broken backward compatibility and reshaped its API substantially in the past (the v1 to v2 rewrite), which is not a foundation this project wants to stand on.
• marshmallow validates and (de)serializes through declarative schema classes with explicit field objects, built around the load and dump cycle. A solid model, but a class you declare, not data you compose.
• cerberus keeps the schema as data, like voluptuous, but as dicts of string rule names rather than live Python objects, so composing and reusing schema pieces means manipulating nested dicts.
• jsonschema validates against the JSON Schema specification. The right tool when the contract is a JSON Schema document, less so as a general Python-side validator.

There simply was not a maintained library that kept voluptuous’s schema-is-data feel while fixing the edges and keeping pace with Python. The comparison page walks through each of these in more depth, including when the other library is the better choice.

What Probatio is

Probatio is a clean-room reimplementation of voluptuous: the same public API, matched by behavior rather than by copied source (ADR-001), so changing import voluptuous to import probatio keeps existing schemas working. That clean-room rule is what lets it be MIT licensed (ADR-002) and fit anywhere voluptuous did.

On top of the drop-in promise, Probatio fixes the rough edges (clean errors on deep or cyclic data, no leaked exceptions from built-ins, a richer error model), adds tooling voluptuous never had (JSON Schema, OpenAPI, dataclass and field-list codecs), and is pure Python with zero required runtime dependencies. It is also fast: on a representative config schema, roughly two to three times faster than voluptuous interpreted, and more once a hot schema compiles itself. The performance page has the honest numbers.

The compatibility is measured, not asserted: Home Assistant’s own config_validation test suite runs against Probatio (the full suite passing), and so does voluptuous’s own 0.16.0 test suite, with every divergence documented. The voluptuous compatibility reference lists those documented deviations name by name.

Who builds it

Probatio is created and written by Franck Nijhof, better known as Frenck, a GitHub Star and the Home Assistant lead, where he has spent years working with voluptuous-validated configuration at a scale and on a hot path that most projects never see. That experience is where Probatio comes from.

Find more of his work at frenck.dev and on GitHub at @frenck.