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,
    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.

Project links

Data verified by PyPI on Aug 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:
Latest release

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 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-1.0.0.tar.gz (1.4 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-1.0.0-py3-none-any.whl (114.4 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for pydantic_versions-1.0.0.tar.gz
Algorithm Hash digest
SHA256 b6bd30f2b8ff139309d37291c3e2fc7d809f086dcdd1b1376f6c26505a971082
MD5 66fc2e197b13c5536fb2af11a6c3198c
BLAKE2b-256 71016c5d25b851f202f53c5d603ecc855f6ae1d52a6e9e0c733b148e0a475c7a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pydantic_versions-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9ad0e90b5e2810fc85a49b9f94174bb0459eaeb14233ae83ad6920aa48c10559
MD5 3937cfdcdcf19d004767786277511d32
BLAKE2b-256 7c4ba5160487c19d32c5e56a63fa0f1cca1ddb9025933d27b6b1b6551b2eba95

See more details on using hashes here.

Provenance

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

This release

1.0.0 This release

2 files

0.3.0

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