pydantic-extra-types

pydantic-extra-types is the official companion package to pydantic for field types that the core maintainers decided “probably shouldn’t exist in the main pydantic lib” — domain-specific value types like phone numbers, ISBNs, MAC addresses, IBANs, currency and country codes, colors, coordinates, cron expressions, semantic versions, and more. Each type is implemented as a proper Pydantic v2 custom type with validation, serialization, and JSON Schema generation built in, so it slots into any Pydantic model exactly like a built-in type.

Most types have zero required dependencies and only need an extra installed (e.g. pydantic-extra-types[pendulum]) when a type wraps a third-party library, such as pendulum-backed datetimes or phonenumbers-backed phone number parsing. Because it’s maintained directly under the pydantic GitHub organization, it tracks pydantic v2 releases closely and is a natural first stop before reaching for a bespoke custom validator.

What You Get

• Dozens of pre-built Pydantic v2 types (phone numbers, ISBN, IBAN, MAC address, coordinates, currency/country/language codes, colors, cron expressions, semantic versions, ULIDs, S3 paths, MongoDB ObjectIds, and more)
• Each type implements full Pydantic v2 validation, serialization, and JSON Schema generation, so it behaves identically to a built-in field type
• Optional extras (pendulum, phonenumbers, etc.) so you only install the third-party dependency a given type actually needs
• Direct maintenance under the pydantic GitHub organization, keeping it closely aligned with pydantic v2’s release cadence

Common Use Cases

• Validating and serializing phone numbers, IBANs, or currency codes in FastAPI/Pydantic request and response models without writing custom validators
• Modeling geographic coordinates, MAC addresses, or ISBNs as first-class typed fields in a data pipeline or API schema
• Adding semantic-version or cron-expression fields to configuration models with built-in parsing and validation
• Standardizing on official, well-tested field types instead of maintaining ad hoc regex-based validators across a codebase

Under The Hood

Architecture - The package is organized as one module per type under pydantic_extra_types/ (phone_numbers.py, color.py, mac_address.py, iban.py, country.py, currency_code.py, cron.py, semantic_version.py, coordinate.py, ulid.py, s3.py, mongo_object_id.py, and more), each independently implementing Pydantic v2’s __get_pydantic_core_schema__/__get_pydantic_json_schema__ protocol so types compose cleanly with the rest of the pydantic ecosystem, with shared JSON-schema helpers centralized in json_schema.py.

Tech Stack - Nearly pure Python (99.65% of the codebase), built on top of pydantic v2’s core-schema APIs and optionally integrating third-party libraries per type (e.g. pendulum for pendulum_dt.py, phonenumbers for phone_numbers.py) as opt-in extras rather than hard dependencies, keeping the base install lightweight.

Code Quality - The tests/ directory mirrors the module layout with one dedicated test file per type (test_phone_numbers.py, test_mac_address.py, test_iban.py, test_cron.py, test_semantic_version.py, etc.), giving each type isolated, focused coverage, backed by CI and Codecov badges in the README. With 73 contributors across 230 commits, the project shows broad community involvement in adding and maintaining individual types.

API Design - Every type is a drop-in Pydantic field annotation (e.g. PhoneNumber, MacAddress, Color) requiring no boilerplate beyond importing and annotating a model field, and the optional-extras installation pattern (pip install pydantic-extra-types[pendulum]) keeps the API surface simple while avoiding unnecessary dependency weight for users who only need a subset of types.