voluptuous
Data validation library for Python using a schema-as-code approach — validates and coerces data with callable schemas. voluptuous features: Schema() class wrapping Python structures (dicts, lists, callables), Required/Optional/Exclusive markers for dict keys, validators as callables (str, int, All, Any, Range, Length, Match, Url, Email), coerce=True for type conversion, extra=PREVENT_EXTRA/ALLOW_EXTRA/REMOVE_EXTRA for unknown keys, humanize_errors() for readable messages, and nested schema composition. Widely used in Home Assistant configuration. Schema-as-Python-code (no YAML/JSON schema format).
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Validation library for enforcing input constraints. No network calls. Avoid using voluptuous.Match() with user-controlled regex patterns — ReDoS risk. Schema instances should be built from trusted code, not user input.
⚡ Reliability
Best When
Validating Python configuration dicts with type coercion — voluptuous's schema-as-code approach integrates naturally with Python without YAML/JSON schema files, widely used in Home Assistant ecosystem.
Avoid When
You need class-based models (use pydantic), JSON Schema (use jsonschema), or rich error reporting (use cerberus).
Use Cases
- • Agent dict validation — from voluptuous import Schema, Required, Optional, All, Range; schema = Schema({Required('host'): str, Required('port'): All(int, Range(min=1, max=65535)), Optional('timeout', default=30): int}); schema({'host': 'localhost', 'port': 8080}) — valid; schema({}) — raises MultipleInvalid — inline Python schema definition; agent validates config dicts at startup
- • Agent coercion with validation — from voluptuous import Schema, Coerce; schema = Schema({'count': Coerce(int), 'ratio': Coerce(float)}); result = schema({'count': '42', 'ratio': '0.5'}) — {'count': 42, 'ratio': 0.5} — Coerce converts strings to types; agent handles JSON where numbers arrive as strings; coercion before type validation
- • Agent union types — from voluptuous import Schema, Any; schema = Schema({'value': Any(str, int, None)}); schema({'value': 'hello'}) — valid; schema({'value': 42}) — valid; schema({'value': None}) — valid; Any() accepts multiple types; agent flexible config fields that accept string or number
- • Agent nested validation — from voluptuous import Schema, Required; schema = Schema({Required('user'): {Required('name'): str, Required('email'): str}, 'settings': {'debug': bool}}); nested dict validation; schema validates structure recursively; agent validates complex nested API payloads
- • Agent extra keys handling — from voluptuous import Schema, REMOVE_EXTRA; schema = Schema({'name': str}, extra=REMOVE_EXTRA); result = schema({'name': 'Alice', 'unknown': 'ignored'}) — {'name': 'Alice'} — extra keys silently removed; agent sanitizes input by stripping unknown fields; PREVENT_EXTRA raises on unknown keys
Not For
- • Class-based models — voluptuous validates dicts only; for dataclass/model validation use pydantic
- • JSON Schema standard — voluptuous has its own schema DSL; for JSON Schema compatibility use jsonschema
- • Complex interdependencies — voluptuous has limited cross-field validation; for complex conditional rules use cerberus
Interface
Authentication
No auth — pure Python validation library.
Pricing
voluptuous is BSD licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Schema raises MultipleInvalid not ValidationError — except voluptuous.MultipleInvalid as e: is required; agent code using except Exception will catch it but str(e) may be cryptic; use voluptuous.humanize.humanize_errors(document, e, schema) for user-friendly messages
- ⚠ Required vs Optional default behavior — Schema({Required('k'): str})({}) raises MultipleInvalid for missing 'k'; Schema({'k': str})({}) — 'k' is optional by default (without Required); agent code: voluptuous default for dict keys is OPTIONAL not Required; must explicitly wrap with Required() for mandatory fields
- ⚠ extra=PREVENT_EXTRA is not the default — Schema({'name': str})({'name': 'a', 'extra': 'b'}) does NOT raise by default; unknown keys pass through; agent code expecting strict input must set: Schema({...}, extra=PREVENT_EXTRA); or use REMOVE_EXTRA to silently strip unknown fields
- ⚠ Coerce vs Python type in schema — Schema({'n': int}) validates that n IS already an int; Schema({'n': Coerce(int)}) converts n to int if possible; agent code receiving JSON strings needs Coerce; using raw int type fails for string '42' with 'expected int' error
- ⚠ List validation syntax — Schema([str]) validates all items are strings; Schema([int, str]) validates items are int OR str (Any); Schema([{'name': str}]) validates list of matching dicts; agent code for list of exact type: use Schema([str]) not Schema(list) which only checks type
- ⚠ Schema callable accepts single arg — all validators in voluptuous are callables taking a single value; custom validator: def positive(v): if v <= 0: raise Invalid('must be positive'); return v; use in schema as: {'score': positive}; raise voluptuous.Invalid not standard exceptions
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for voluptuous.
Scores are editorial opinions as of 2026-03-06.