11 Essential Pydantic v2 Practices to Avoid Common Pitfalls

Data validation is not a "nice‑to‑have" feature but the armor of a reliable system. The author shares eleven hard‑earned best practices from a year of production use of Pydantic v2, aimed at developers building FastAPI or similar services.

1. Start with strong types, even if it feels tedious

A common mistake is using vague type hints like profile: dict or score: list, which hide bugs. The correct approach is to specify concrete generics or nested models:

# ✅ Clear types
class User(BaseModel):
    profile: dict[str, str]  # explicit key/value types
    score: list[float]

class Profile(BaseModel):
    full_name: str
    bio: str | None = None

class User(BaseModel):
    profile: Profile
    score: list[float]

Note: Precise type hints act as a contract with future maintainers and enable IDE autocompletion, catching errors the moment data enters the system.

2. Validate at the system boundary, not deep inside business logic

Place validation as soon as data arrives (e.g., in an API handler) so downstream code can safely assume a valid structure:

# API request arrives
def create_user_api(request):
    user = User.model_validate(request.json())
    # All downstream code trusts <code>user</code> now

config = Settings.model_validate(json.load(open("config.json")))
product = Product.model_validate(llm_response)

3. Keep validators focused on validation, not conversion or calculation

Pydantic v2 automatically converts compatible types, so manual conversion inside validators is unnecessary. Use validators only for business rules:

# ✅ Let Pydantic handle conversion, then validate
class Product(BaseModel):
    price: float

    @field_validator("price")
    def ensure_non_negative(cls, value):
        if value < 0:
            raise ValueError("价格不能为负")
        return value

4. Compose small models instead of a monolithic "god class"

Break a large JSON schema into reusable sub‑models for readability and maintainability:

# Small, composable models
class Address(BaseModel):
    street: str
    city: str
    zip_code: str

class Customer(BaseModel):
    name: str
    email: str
    shipping_address: Address | None = None
    billing_address: Address | None = None

class Order(BaseModel):
    order_id: int
    customer: Customer
    items: list[OrderItem]

Analogy: Like building a house with bricks, small models can be reused across different contexts and are easier to test.

5. Use Annotated to encapsulate domain constraints

Define reusable constrained types such as percentages or non‑negative integers:

from typing import Annotated
from pydantic import Field

Percentage = Annotated[float, Field(ge=0, le=1)]
NonNegativeInt = Annotated[int, Field(ge=0)]
EmailStr = Annotated[str, Field(pattern=r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$")]

class Discount(BaseModel):
    rate: Percentage      # automatically constrained to 0‑1
    max_uses: NonNegativeInt
    contact: EmailStr

6. When data isn’t a dict, use RootModel

For raw lists or strings, RootModel validates without forcing a dict structure:

from pydantic import RootModel

class TagList(RootModel[list[str]]):
    pass

tags = TagList.model_validate(["python", "pydantic", "tips"])
print(tags.root)  # ['python', 'pydantic', 'tips']

7. Make stable models immutable

Mark configuration or snapshot models as frozen to prevent accidental mutation:

class Settings(BaseModel, frozen=True):
    host: str
    port: int
    debug: bool = False

Any attempt to modify an attribute raises TypeError, clearly signalling read‑only intent.

8. Resolve circular references with model_rebuild()

After defining mutually referencing models, call model_rebuild() to update internal references and avoid NameError:

class Node(BaseModel):
    name: str
    children: list["Node"] | None = None

Node.model_rebuild()  # resolves forward references

9. Write specific error messages

Instead of generic "invalid input", raise errors that pinpoint the offending field and requirement:

@field_validator("price")
def check_positive(cls, v):
    if v <= 0:
        raise ValueError("price 必须大于 0")
    return v

10. Keep business logic out of models

Models should describe data shape only. Place calculations and side‑effects in service‑layer code:

# ❌ Model mixes logic
class Order(BaseModel):
    items: list[Item]
    discount: float
    def total(self):
        ...

# ✅ Separate service
class OrderCalculator:
    def calculate_total(order: Order) -> float:
        raw = sum(item.price * item.quantity for item in order.items)
        return raw * (1 - order.discount)

11. Validate all external data, including data from databases

Apply the same validation discipline to data read from DB, message queues, or config files:

# API request
def handle_request(data):
    validated = MyModel.model_validate(data)

# Database read
def fetch_user(user_id):
    row = db.fetch_one(...)
    return User.model_validate(row)

# Message queue
def process_message(msg):
    event = Event.model_validate(json.loads(msg))

# Config file
settings = Settings.model_validate(yaml.safe_load(open("app.yml")))

Adopting this habit eliminates scattered defensive checks and simplifies testing.

Conclusion

Pydantic v2 taught the author that data validation is not a defensive programming burden but a core design principle; when the code trusts the shape of its data, business logic becomes dramatically clearer.