pydantic-versions

Bring version control and history to your Pydantic schemas.

CI status PyPI version Supported Python versions Documentation status License

pydantic-versions logo

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,
    VersionTransition,
    field_default,
    field_removed,
)


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


def upgrade_v1(data: dict) -> dict:
    data.setdefault("new_feature", False)
    return data


APP_CONFIG_SCHEMA = SchemaFamily(
    model=AppConfig,
    name="app_config",
    versions=(
        SchemaVersion(
            "1",
            patches=(
                field_default("timeout", 5.0),
                field_removed("new_feature"),
            ),
        ),
        SchemaVersion("2"),
    ),
    transitions=(VersionTransition("1", "2", upgrade=upgrade_v1),),
    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.dump(version="1")
assert v1_config == {"timeout": 5.0, "retries": 3, "schema_version": "1"}

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.
  • make test: run pytest.
  • make docs-build: build the docs site.

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dariuszpanas from gravatar.com dariuszpanas

Credits

Author: Dariusz Panas

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.12

Tags

migrations pydantic schema-versioning schemas validation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydantic_versions-0.3.0.tar.gz (1.2 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pydantic_versions-0.3.0-py3-none-any.whl (42.2 kB view details)

Uploaded Python 3

File details

Details for the file pydantic_versions-0.3.0.tar.gz.

File metadata

  • Download URL: pydantic_versions-0.3.0.tar.gz
  • Upload date:
  • Size: 1.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pydantic_versions-0.3.0.tar.gz
Algorithm Hash digest
SHA256 b07ab310b27d7f968837fbfcf78dfdbe2fc399bc2d697072473691ecb8bedce1
MD5 3c215a2f55c6e5f3bfda913c9711e315
BLAKE2b-256 305010476abb6d76ec44557f264c3451dda73ba0973564eeacff897fb8813eff

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydantic_versions-0.3.0.tar.gz:

Publisher: release.yml on dariuszpanas/pydantic-versions

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydantic_versions-0.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for pydantic_versions-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1b21279753da8497ff4f834d16dbc8f520b516dc1d8bd5f423277f4eafdff283
MD5 8147fc1224dc33c71737303e9a591053
BLAKE2b-256 340b9a39db54cefc6a9f2ac351fe2258b1c46b827b5406bb38e413b9a1a9018d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydantic_versions-0.3.0-py3-none-any.whl:

Publisher: release.yml on dariuszpanas/pydantic-versions

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.0.0

2 files

This release

0.3.0 This release

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page