Pydantic v2 skill for Codex

Done well means: models validate at the boundary and nowhere else, constraints live in types rather than in hand-written if chains, serialization is explicit (mode="json"), and no v1-era API (.dict(), @validator, class Config) survives a migration.

Before changing anything

• Check the installed version: python -c "import pydantic; print(pydantic.VERSION)". Advice below targets 2.7+; features added later are marked.
• Grep for v1 usage to size a migration: rg -n "\.dict\(|\.json\(|parse_obj|@validator|@root_validator|class Config:|from pydantic\.v1|orm_mode" src
• Read AGENTS.md for where schemas live and whether FastAPI or SQLModel is involved; both pin compatible Pydantic ranges.

Model defaults

from datetime import datetime
from typing import Annotated, Literal
from pydantic import BaseModel, ConfigDict, EmailStr, Field

PositiveCents = Annotated[int, Field(ge=0, description="Amount in minor units")]

class LineItem(BaseModel):
    model_config = ConfigDict(extra="forbid", frozen=True, str_strip_whitespace=True)

    sku: Annotated[str, Field(min_length=1, max_length=64, pattern=r"^[A-Z0-9-]+$")]
    quantity: Annotated[int, Field(gt=0, le=10_000)]
    unit_price: PositiveCents

class Order(BaseModel):
    model_config = ConfigDict(extra="forbid")

    id: str
    customer_email: EmailStr               # needs the email-validator extra
    status: Literal["draft", "paid", "shipped"] = "draft"
    items: list[LineItem] = Field(min_length=1)
    created_at: datetime
    note: str | None = None                # optional AND defaulted; see gotchas

Config key	Use when
extra="forbid"	Request bodies and config files: typos become errors
extra="ignore" (default)	Consuming third-party payloads that grow fields
frozen=True	Value objects; also makes instances hashable
strict=True	No coercion at all (“1” is not an int). Use per field with Field(strict=True) for IDs and money
from_attributes=True	Building models from ORM objects (model_validate(orm_obj))
validate_assignment=True	Mutable models whose fields change after construction
populate_by_name=True (2.11+: validate_by_name=True)	Accept both alias and field name

Validators: pick the narrowest tool

Need	Tool
Range, length, regex	Field(...) constraints inside Annotated
Reusable transform on a type	Annotated[str, AfterValidator(fn)] / BeforeValidator(fn)
One field, needs custom logic	@field_validator("name")
Cross-field rule	@model_validator(mode="after")
Reshape raw input before parsing	@model_validator(mode="before")

from typing import Self
from pydantic import AfterValidator, StringConstraints, field_validator, model_validator

RESERVED = {"admin", "api", "login"}

def _not_reserved(v: str) -> str:
    if v in RESERVED:
        raise ValueError(f"'{v}' is reserved")
    return v

Slug = Annotated[
    str,
    StringConstraints(strip_whitespace=True, to_lower=True, pattern=r"^[A-Za-z0-9-]+$"),
    AfterValidator(_not_reserved),
]

class Booking(BaseModel):
    slug: Slug
    start: datetime
    end: datetime
    tags: list[str] = []

    @field_validator("tags", mode="after")
    @classmethod
    def dedupe(cls, v: list[str]) -> list[str]:
        return sorted(set(v))

    @model_validator(mode="after")
    def check_range(self) -> Self:
        if self.end <= self.start:
            raise ValueError("end must be after start")
        return self

• Raise ValueError (or PydanticCustomError for a custom error type/code). Do not raise ValidationError yourself and never use assert (stripped under python -O).
• mode="after" validators receive parsed, typed values; prefer them. mode="before" receives raw input of any type and must handle that.
• An after model validator must return self.

Discriminated unions

class Card(BaseModel):
    kind: Literal["card"]
    last4: str

class Bank(BaseModel):
    kind: Literal["bank"]
    iban: str

class Payment(BaseModel):
    method: Annotated[Card | Bank, Field(discriminator="kind")]

Without the discriminator, Pydantic tries each member (“smart” mode) and error messages list failures for every branch. With it, validation is faster and errors name the right model.

Validating things that are not models

from pydantic import TypeAdapter

ItemsAdapter = TypeAdapter(list[LineItem])        # build once at module level; construction is costly
items = ItemsAdapter.validate_json(raw_bytes)     # faster than json.loads + validate_python
schema = ItemsAdapter.json_schema()

Serialization

order.model_dump()                       # Python objects (datetime stays datetime)
order.model_dump(mode="json")            # JSON-safe primitives
order.model_dump_json(exclude_none=True, by_alias=True)
order.model_copy(update={"status": "paid"})   # no validation of the update; re-validate if needed

Custom output with @field_serializer("amount") or a computed value with @computed_field on a @property (included in dumps and JSON schema).

Settings from the environment

from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix="APP_", env_file=".env", env_nested_delimiter="__", extra="ignore"
    )
    database_url: str
    api_key: SecretStr
    debug: bool = False
    pool_size: int = 10

settings = Settings()   # APP_DATABASE_URL, APP_API_KEY, APP_DB__... for nested models

• pydantic-settings is a separate package (install needs network/approval in a sandbox).
• Precedence: init kwargs > environment variables > .env file > defaults.
• SecretStr hides values in repr and logs; call .get_secret_value() only where needed.
• Instantiate once (module-level or functools.cache) and fail at startup, not at first use.

Migrating from v1

uvx bump-pydantic src/     # needs network; rewrites most mechanical changes, review the diff

v1	v2
.dict(), .json()	.model_dump(), .model_dump_json()
parse_obj, parse_raw, from_orm	model_validate, model_validate_json, model_validate + from_attributes=True
class Config:	model_config = ConfigDict(...)
@validator, @root_validator	@field_validator (+ @classmethod), @model_validator
orm_mode, allow_population_by_field_name	from_attributes, populate_by_name
Field(regex=...), min_items, const=True	pattern=, min_length, Literal[...]
__fields__, update_forward_refs(), .copy()	model_fields, model_rebuild(), .model_copy()
Optional[int] implied = None	int | None is required unless you write = None
each_item=True validators	Validate the item type with Annotated[...] instead

Staged path for big codebases: from pydantic import v1 as pydantic_v1 keeps untouched modules on the v1 API inside v2 while you migrate module by module. Never mix v1 and v2 models in one nested structure.

Gotchas

• Lax mode coerces: "42" becomes 42, "true" becomes True, and an int field accepts 4.0 but rejects 4.5. Use strict where coercion would hide client bugs.
• str | None without a default is required; clients must send null explicitly.
• Mutable defaults (tags: list[str] = []) are safe in Pydantic (copied per instance), unlike dataclasses. Do not “fix” them with default_factory unless the factory computes something.
• Field names starting with model_ collide with Pydantic’s namespace and warn.
• In StringConstraints, pattern is checked before to_lower is applied, so a lowercase-only regex rejects "Hello". Make the pattern accept both cases, or lowercase in a BeforeValidator.
• model_construct() skips validation entirely; use only for data you already validated.
• Validation errors include input values; scrub e.errors(include_input=False) before logging user payloads that may hold secrets.

Verification

• Tests cover one valid payload and one invalid payload per validator, asserting the error loc and type: exc.value.errors()[0]["loc"] == ("items", 0, "quantity").
• Model.model_json_schema() matches what API consumers expect (diff it against the published OpenAPI schema when FastAPI is involved).
• After a migration: rg "\.dict\(|@validator|class Config:" returns nothing in migrated modules, and the full test suite passes with warnings enabled (pytest -W error::DeprecationWarning where practical).