Pydantic v2 Best Practices

Pydantic is the most widely used data validation library for Python. This skill covers idiomatic patterns, common pitfalls, and performance guidance for Pydantic v2 (the current major version).

Models

Define models by inheriting from

BaseModel

python

from pydantic import BaseModel, ConfigDict

class User(BaseModel):
    model_config = ConfigDict(str_strip_whitespace=True, extra='forbid')

    id: int
    name: str
    email: str | None = None

Key rules:

Use

model_config = ConfigDict(...)

— never the deprecated V1

class Config

Set
```
extra='forbid'
```
to reject unexpected fields in strict APIs; use
```
extra='ignore'
```
(default) or
```
extra='allow'
```
when appropriate.
Avoid naming a field the same as its type annotation (
```
int: int
```
breaks validation).

Validate data correctly

python

# From dict / Python objects
user = User.model_validate({'id': 1, 'name': 'Alice'})

# From JSON bytes/str — faster than model_validate(json.loads(...))
user = User.model_validate_json('{"id": 1, "name": "Alice"}')

# From ORM / arbitrary objects
class UserORM: ...
user = User.model_validate(orm_obj, from_attributes=True)

Always prefer

model_validate_json()

over

model_validate(json.loads(...))

for JSON input — the former validates internally without an extra Python-side parse step.

Use

model_post_init

instead of a custom

__init__

python

from typing import Any
from pydantic import BaseModel

class MyModel(BaseModel):
    value: int

    def model_post_init(self, context: Any) -> None:
        # Runs after all field validators succeed
        self._cache: dict = {}

Defining a custom

__init__

bypasses validation parameters (strictness, extra, context). Use

model_post_init

for side effects after initialization.

Copy models with

model_copy

python

updated = user.model_copy(update={'name': 'Bob'})
deep_copy = user.model_copy(deep=True)

Fields

Use the

Annotated

pattern for reusable constraints

python

from typing import Annotated
from pydantic import BaseModel, Field

PositivePrice = Annotated[float, Field(gt=0, description='Price in USD')]
ShortString = Annotated[str, Field(max_length=100)]

class Product(BaseModel):
    name: ShortString
    price: PositivePrice
    quantity: Annotated[int, Field(ge=0)] = 0

The annotated pattern makes constraints composable and reusable across models, unlike

field: type = Field(...)

which ties the constraint to one model.

Provide field metadata for JSON Schema

python

from pydantic import BaseModel, Field

class Article(BaseModel):
    title: str = Field(
        min_length=1,
        max_length=200,
        title='Article Title',
        description='The main headline',
        examples=['Pydantic v2 released'],
    )

Use

default_factory

for mutable defaults

python

from pydantic import BaseModel, Field

class Order(BaseModel):
    # Correct — factory called per instance
    items: list[str] = Field(default_factory=list)
    tags: set[str] = Field(default_factory=set)

Pydantic handles non-hashable defaults (like

[]

{}

) safely by deep-copying them, but

default_factory

is the explicit, recommended approach.

Use aliases to decouple field names from wire formats

python

from pydantic import BaseModel, Field, ConfigDict

class Response(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    user_id: int = Field(alias='userId')          # validation + serialization
    created_at: str = Field(serialization_alias='createdAt')  # serialization only

Validators

Choose the right validator mode

Mode	When to use
`after`	Post-type-coercion checks; input is already the correct type
`before`	Pre-coercion transformations; input may be raw/arbitrary
`plain`	Full replacement of Pydantic's logic for a field
`wrap`	Need to intercept errors or run code both before and after

Prefer

after

validators — they receive the already-coerced value and are easier to type correctly.

Write reusable validators with the annotated pattern

python

from typing import Annotated
from pydantic import AfterValidator, BaseModel

def must_be_even(v: int) -> int:
    if v % 2 != 0:
        raise ValueError(f'{v} is not even')
    return v

EvenInt = Annotated[int, AfterValidator(must_be_even)]

class Config(BaseModel):
    batch_size: EvenInt
    worker_count: EvenInt

Use

field_validator

to apply one function to multiple fields

python

from pydantic import BaseModel, field_validator

class User(BaseModel):
    first_name: str
    last_name: str

    @field_validator('first_name', 'last_name', mode='before')
    @classmethod
    def strip_whitespace(cls, v: str) -> str:
        return v.strip()

Use

model_validator

for cross-field checks

python

from typing_extensions import Self
from pydantic import BaseModel, model_validator

class DateRange(BaseModel):
    start: int
    end: int

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

Raise the right exception type in validators

```
ValueError
```
— standard choice for most validation failures.
```
AssertionError
```
— works but is skipped under Python's
```
-O
```
flag; avoid in production validators.
```
PydanticCustomError
```
— use when custom error types and structured error metadata are needed.

python

from pydantic_core import PydanticCustomError

raise PydanticCustomError(
    'invalid_format',
    'Value {value!r} does not match the expected format',
    {'value': v},
)

Pass context to validators when needed

python

from pydantic import BaseModel, ValidationInfo, field_validator

class Document(BaseModel):
    text: str

    @field_validator('text', mode='after')
    @classmethod
    def filter_words(cls, v: str, info: ValidationInfo) -> str:
        if isinstance(info.context, dict):
            banned = info.context.get('banned_words', set())
            v = ' '.join(w for w in v.split() if w not in banned)
        return v

doc = Document.model_validate(
    {'text': 'hello world'},
    context={'banned_words': {'hello'}},
)

Error Handling

Catch

ValidationError

and inspect

.errors()

for structured detail:

python

from pydantic import BaseModel, ValidationError

class Item(BaseModel):
    price: float
    quantity: int

try:
    Item(price='bad', quantity=-1)
except ValidationError as exc:
    for error in exc.errors():
        print(error['loc'], error['msg'], error['type'])

One

ValidationError

aggregates all field errors — never raised per-field individually.

Quick Reference

Task	Recommended API
Validate from dict	`Model.model_validate(data)`
Validate from JSON	`Model.model_validate_json(json_str)`
Validate from ORM	`Model.model_validate(obj, from_attributes=True)`
Dump to dict	`model.model_dump()`
Dump to JSON	`model.model_dump_json()`
Dump only set fields	`model.model_dump(exclude_unset=True)`
Copy with changes	`model.model_copy(update={...})`
Skip validation	`Model.model_construct(...)` — only for pre-validated data
Rebuild after forward refs	`Model.model_rebuild()`

Additional Resources

references/validators-and-fields.md
— Detailed validator modes, field constraints, discriminated unions, and computed fields.

references/serialization-and-config.md
— Serializers,

model_dump

options,

ConfigDict

reference, and ORM integration.

references/performance.md
— Performance tips:
```
TypeAdapter
```
reuse, tagged unions,
```
TypedDict
```
vs nested models,
```
FailFast
```
, and more.

pydantic

NPX Install

Tags

SKILL.md Content

Pydantic v2 Best Practices

Models

Define models by inheriting from
`BaseModel`

Validate data correctly

Use
`model_post_init`
instead of a custom
`init`

Copy models with
`model_copy`

Fields

Use the
`Annotated`
pattern for reusable constraints

Provide field metadata for JSON Schema

Use
`default_factory`
for mutable defaults

Use aliases to decouple field names from wire formats

Validators

Choose the right validator mode

Write reusable validators with the annotated pattern

Use
`field_validator`
to apply one function to multiple fields

Use
`model_validator`
for cross-field checks

Raise the right exception type in validators

Pass context to validators when needed

Error Handling

Quick Reference

Additional Resources