pydantic-versions

Bring version control and history to your Pydantic schemas.

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 Jul 24, 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 Jul 24, 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.2.0.tar.gz (999.3 kB 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.2.0-py3-none-any.whl (41.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: pydantic_versions-0.2.0.tar.gz
  • Upload date:
  • Size: 999.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pydantic_versions-0.2.0.tar.gz
Algorithm Hash digest
SHA256 134acda2d9a5711dce28972071f944ceeb4583cd8ab642205016232605fb7929
MD5 ea7d05a298fee49f3421c1de8a14a750
BLAKE2b-256 dceada3795488805767cd9747f8725497b2dd891317d8464397a16559078fd32

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydantic_versions-0.2.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.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for pydantic_versions-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 72759fd3f92941eed4c1b7473f12b98b32f38b1288a9f997b40a3eec82000192
MD5 96c58847e889a8de3881981cbe71e4e3
BLAKE2b-256 435b4cb6ecbf1363940fc49b55baabf815827087d30f7efe1cdbd3cc4def8626

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydantic_versions-0.2.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

0.3.0

2 files

This release

0.2.0 This release

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