Installation

No extra packages required.

pip install zodify

Basic validation

Pass the schema first, data second. Types are strict; extra keys are rejected.

from zodify import validate

schema = {"port": int, "debug": bool}
data = {"port": 8080, "debug": False}

print(validate(schema, data))

Output

{'port': 8080, 'debug': False}

Task guides

Choose the input you are working with. Each guide includes a complete example and explains its limits.

API reference

Look up a specific behavior below. The full API reference includes parameter tables, env-file parsing, and JSON export limits.

Supported types

Use exact Python types, nested dict schemas, one-element list schemas, unions, and predicates.

Optional keys and defaults

Optional controls missing keys; a union with None controls nullable values. Defaults are inserted as supplied, without copying or validation.

Unions

With coercion enabled, string input follows declared union order; non-string exact matches take precedence.

Nested schemas

Dict shapes and one-element list schemas validate nested containers. The default maximum depth is 32.

Optional class syntax

Schema declarations offer attribute access using the same validation engine.

Custom validators

Predicates return truthy for acceptance; they receive and preserve the original value. Callback errors may expose their own messages.

Environment variables

The env(name, cast, default) helper reads process environment variables. The load_env(path, schema=...) helper parses a .env file without mutating os.environ; with a schema it defaults to coercion and stripping unknown keys. Raw mode returns parsed strings.

Error handling

Text mode raises ValueError. Choose error_mode="structured" for ValidationError. Review error contents before logging them.

Structured errors

ValidationError.issues retains path, message, expected, and got fields. Engine structured errors also expose immutable canonical details with machine codes and typed locations; manually constructed legacy errors can have details=None.

Start here