nested-validator-python
A tiny, fast, list-aware, nested rules validator for Python — with smart type coercion. By Autobit
nested-validator-python lets you declare validation as compact strings (e.g. required|int|gte:0) and recursively validate complex payloads (lists of dicts, lists within lists, etc.) using a clean __field convention for per-item rules. It also coerces common types (ints, floats, booleans, timestamps) so your validated result is ready for persistence.
Ideal for service layers, ORMs, and lightweight APIs where you want strict inputs without heavy dependencies.
Features
✅ String rules like required|min:3|max:100|email
🔁 Arbitrary nesting via __ per-item rules for lists
🧠 Type coercion for int, numeric, boolean, timestamp
🔗 Cross-field rules: same, different, before, after, confirmed
🧾 Clear, indexed errors for deep list paths (items[2].props[0].key)
🧰 Zero heavy deps; Python 3.9+ (tested up to 3.12)
Install
Using GitHub (until PyPI release):
pip install "git+https://github.com/AutobitDevs/nested-validator-python.git"
Or copy the core file into your project (e.g., utils/validator.py) and import from there.
Quick Start
from nested_validator import Validator
payload = { "name": "Equities", "properties": [ {"key": "margin", "value": "5", "default": "yes"}, {"key": "lot", "value": "50"} ] }
rules = { "name": "required|string|min:3|max:100", "properties": "required|list", "__properties": { # per-item rules for 'properties' "key": "required|string|min:1|max:100", "value": "int|gte:0", # "5" -> 5 (coerced) "default": "boolean" # "yes" -> True (coerced) } }
v = Validator(rules) validated = v.validate(payload)
if v.fails(): print(v.messages()) # full error map else: print(validated) # { # "name": "Equities", # "properties": [ # {"key": "margin", "value": 5, "default": True}, # {"key": "lot", "value": 50} # ] # }
Deeply Nested Example payload = { "orders": [ { "id": "1001", "lines": [ {"sku": "X", "qty": "2"}, {"sku": "Y", "qty": 1} ] } ] }
rules = { "orders": "required|list", "__orders": { "id": "required|string", "lines": "required|list", "__lines": { "sku": "required|string|min:1", "qty": "required|int|gte:1" } } }
Errors are indexed, e.g. orders[0].lines[1].qty.
Rules Reference
Basic
required, string, int, numeric, boolean, timestamp
min:, max:, size:
in:a,b,c
email, regex:
date or date:%Y-%m-%d (default %Y-%m-%d)
gt:, lt:, gte:, lte:
Cross-field
same:<other_field>, different:<other_field>
confirmed (requires _confirmation)
after:<other_date_field>, before:<other_date_field> (YYYY-MM-DD)
Lists & Nesting
Mark list fields with "list".
Provide item rules at the same level via __.
You can nest this pattern as deeply as needed.
Type Coercion (Summary) Rule Accepts Produces int "42", 42.0 42 numeric "3.14", 2 3.14, 2 boolean true/false/yes/no/on/off/1/0 True/False timestamp UNIX seconds as str or int int
Coerced values are written back into the input dict before building validated.
Minimal Service Example class Instrument(Service): async def createCategory(self): data = self.req["payload"] v = Validator({ "name": "required|string|min:3|max:100", "properties": "required|list", "__properties": { "key": "required|string|min:1|max:100", "value": "int|gte:0", "default": "max:100" } }) validated = v.validate(data) if v.fails(): return await self.response("failed", v.message())
# Optional uniqueness check (ONQL)
q = self.ORM.build("fintrabit.instrument_categories[name=$1]", validated["name"])
if await self.ORM.onql(q):
return await self.response("failed", "Category name already exists")
res = await self.ORM.insert("instrument_category", validated)
return await self.response("success", "Category created", res)
API
Validator(rules: dict) – create a validator
validate(data: dict) -> dict – validates and returns normalized data (coerced)
fails() -> bool – any errors?
messages() -> dict – full error map (deep, indexed)
message() -> str|None – first error string (UI-friendly)
Custom rules: add a method validate(self, field, value, param, data) that raises ValidationError on failure.
Roadmap
Pluggable unique:<model.field> adapters
i18n error messages
Strict mode (reject unknown fields)
PyPI package
Contributing
PRs welcome! Please:
Keep it dependency-light
Add tests for new behavior
Explain changes clearly
Run tests (example):
pytest -q
License
MIT
Credits
By Autobit © Autobit Software Services Pvt Ltd