Pydantic Best Practices

Pydantic (project skill)

Pydantic v2 performance + contract practices for this api-template. Pair with .claude/rules/contracts/pydantic-dtos.md. The Cursor twin lives at .cursor/skills/pydantic-best-practices/SKILL.md - keep the two in sync when updating either.

Essentials for this repo

• One owner per wire shape under app/dtos/ / app/enums/ - no duplicate mirrors (guardrails: "one source of truth").
• No business logic in DTO modules; keep Field descriptions OpenAPI-friendly and client-safe (no secrets / PII).
• Settings live in app/core/config.py; never commit real secrets - sync .env.template only.
• Use docs-researcher / Context7 for version-sensitive Pydantic questions.

Prefer model_validate_json() over model_validate(json.loads(...))

model_validate(json.loads(...)) parses JSON in Python, converts to a dict, then validates. model_validate_json() validates directly from the raw JSON string inside Rust - skip the intermediate dict entirely.

import json
from pydantic import BaseModel


class User(BaseModel):
    id: int
    name: str


raw = '{"id": 1, "name": "Alice"}'

# DO NOT DO THIS
user = User.model_validate(json.loads(raw))

# Do this
user = User.model_validate_json(raw)

Exception: when using a 'before' or 'wrap' validator on the model, the two-step method can be faster. Benchmark before assuming.

Instantiate TypeAdapter once, not per call

Every TypeAdapter(...) call builds a new validator and serializer. Move it to module level or a class attribute.

from pydantic import TypeAdapter

# DO NOT DO THIS
def parse_ids(data: list) -> list[int]:
    adapter = TypeAdapter(list[int])
    return adapter.validate_python(data)

# Do this
_ids_adapter = TypeAdapter(list[int])

def parse_ids(data: list) -> list[int]:
    return _ids_adapter.validate_python(data)

Use concrete types instead of abstract collections

Sequence forces an isinstance check and tries multiple concrete types. Mapping does the same. Use list, tuple, or dict when you know the exact type.

from collections.abc import Mapping, Sequence
from pydantic import BaseModel


# DO NOT DO THIS
class SlowModel(BaseModel):
    items: Sequence[int]
    meta: Mapping[str, str]


# Do this
class FastModel(BaseModel):
    items: list[int]
    meta: dict[str, str]

Use Any when validation is not needed

Pydantic skips all validation for Any fields. Use it when the value is already trusted or will be validated elsewhere.

from typing import Any
from pydantic import BaseModel


class Event(BaseModel):
    name: str
    payload: Any  # raw blob, no validation cost

Avoid subclassing primitives for extra attributes

Pydantic must inspect subclasses of primitives specially. Carry extra state in a model field instead.

from pydantic import BaseModel


# DO NOT DO THIS
class CompletedStr(str):
    def __init__(self, s: str):
        self.s = s
        self.done = False


# Do this
class Task(BaseModel):
    value: str
    done: bool = False

Use discriminated (tagged) unions over plain unions

Plain unions try each branch in order. A discriminated union resolves the type in O(1) via a Literal discriminator field.

from typing import Any, Literal
from pydantic import BaseModel, Field


class DivModel(BaseModel):
    el_type: Literal['div'] = 'div'
    class_name: str | None = None
    children: list[Any] | None = None


class SpanModel(BaseModel):
    el_type: Literal['span'] = 'span'
    class_name: str | None = None
    contents: str | None = None


class ButtonModel(BaseModel):
    el_type: Literal['button'] = 'button'
    class_name: str | None = None
    contents: str | None = None


class InputModel(BaseModel):
    el_type: Literal['input'] = 'input'
    class_name: str | None = None
    value: str | None = None


# DO NOT DO THIS
class HtmlSlow(BaseModel):
    contents: DivModel | SpanModel | ButtonModel | InputModel


# Do this
class Html(BaseModel):
    contents: DivModel | SpanModel | ButtonModel | InputModel = Field(
        discriminator='el_type'
    )

Use TypedDict over nested models for inner structures

TypedDict has lower overhead than a full BaseModel when the inner structure doesn't need methods, validators, or serialization customisation.

from typing import TypedDict
from pydantic import BaseModel


# Prefer this for nested, plain data shapes
class Address(TypedDict):
    street: str
    city: str
    zip_code: str


class User(BaseModel):
    name: str
    address: Address

Avoid wrap validators on hot paths

Wrap validators materialise data as Python objects during validation, bypassing the Rust-side fast path. Prefer before, after, or field_validator modes.

from pydantic import BaseModel, field_validator


# Avoid on hot paths
# @model_validator(mode='wrap')
# def validate_model(cls, value, handler): ...

# Prefer
class Order(BaseModel):
    amount: float

    @field_validator('amount')
    @classmethod
    def must_be_positive(cls, v: float) -> float:
        if v <= 0:
            raise ValueError('amount must be positive')
        return v

Use FailFast on sequences to short-circuit on first error

Available from Pydantic v2.8+. Trades full error visibility for reduced work when early rejection is acceptable.

from typing import Annotated
from pydantic import FailFast, TypeAdapter, ValidationError

_bool_list_adapter = TypeAdapter(Annotated[list[bool], FailFast()])

try:
    _bool_list_adapter.validate_python([True, 'invalid', False, 'also invalid'])
except ValidationError as exc:
    # Only the first error is reported - stops after 'invalid'
    print(exc)

Do not apply FailFast when you need to surface all validation errors to an end user.