pydantic-versions

Bring version control and history to your Pydantic schemas.

pydantic-versions lets projects register ordered schema versions, derive historical Pydantic models from a current model, validate historical payloads, render historical config shapes, and upgrade data to the current model.

Install

pip install pydantic-versions

With uv:

uv add pydantic-versions

Example

Schema versions are independent from software versions. A config payload can declare the schema it uses, and the latest software can still validate and upgrade it:

from pydantic import BaseModel
from pydantic_versions import (
    SchemaFamily,
    SchemaVersion,
    field_default,
    field_removed,
)


class AppConfig(BaseModel):
    timeout: float = 10.0
    retries: int = 3
    new_feature: bool = False


APP_CONFIG_SCHEMA = SchemaFamily(
    model=AppConfig,
    name="app_config",
    versions=(
        SchemaVersion(
            "1",
            patches=(
                field_default("timeout", 5.0),
                field_removed("new_feature"),
            ),
        ),
        SchemaVersion("2"),
    ),
    missing_version="1",
)


result = APP_CONFIG_SCHEMA.validate({"schema_version": "1", "retries": 2})
assert result.current_model == AppConfig(timeout=5.0, retries=2, new_feature=False)

v1_config = APP_CONFIG_SCHEMA.defaults_for(version="1")
assert v1_config == {"timeout": 5.0, "retries": 3, "schema_version": "1"}

defaults_for() constructs the requested wire version directly, so historical defaults do not depend on a downgrade route from the current version. Use dump(version=..., data=current_config) when converting actual current data.

missing_version is only for legacy config files that do not contain a schema version field. For example, missing_version="1" means "if a payload has no schema_version, treat it as an old v1 config." If you do not set it, unversioned input raises MissingSchemaVersionError.

The current model remains ordinary; its growing history can live in another module. The decorators remain available as a compact compatibility style. The docs include external-family guidance, a larger nested config example, and adoption guidance for choosing patches, migrations, metadata, and legacy unversioned fallbacks.

Development

Install dependencies:

uv sync

Run the main checks:

make ci

Useful commands:

• make format: format with Ruff.
• make lint: lint and auto-fix with Ruff.
• make typecheck: run ty plus the external mypy consumer contract.
• make dead-code: scan production code with Vulture and reviewed local exceptions.
• make test: run pytest.
• make docs-build: build the docs site.