10 Advanced Pydantic Tricks to Strengthen FastAPI Request Validation

When a payment endpoint expects a price field of type float, Pydantic will silently coerce a string like "29.99" into a float. This default behaviour, while convenient for rapid prototyping, can hide bugs and introduce security risks in production APIs.

1. Enable Strict Mode to Block Automatic Type Conversion

By default Pydantic tries to make the data "fit". To reject mismatched types, set ConfigDict(strict=True) on the model:

from pydantic import BaseModel, ConfigDict

# Default behaviour – automatic conversion
class PaymentLoose(BaseModel):
    amount: float
    currency: str

PaymentLoose(amount="29.99", currency=123)  # succeeds, but may be wrong

# Strict mode – reject type mismatches
class PaymentStrict(BaseModel):
    model_config = ConfigDict(strict=True)
    amount: float
    currency: str

PaymentStrict(amount="29.99", currency="USD")  # ValidationError: amount - Input should be a valid number

Strict mode can also be applied to individual fields using StrictInt or StrictStr.

Note: Enable strict mode for models that handle amounts, quantities, or other sensitive data to avoid silent corruption.

2. Use Field Constraints Instead of Custom Validators

Before writing a custom @field_validator, check whether built‑in Field() constraints are sufficient:

from pydantic import BaseModel, Field

class CreateUser(BaseModel):
    username: str = Field(min_length=3, max_length=30, pattern=r'^[a-zA-Z0-9_]+$')
    email: EmailStr
    age: int = Field(ge=13, le=120)
    bio: str | None = Field(default=None, max_length=500)
    referral_code: str | None = Field(default=None, min_length=8, max_length=8)

These constraints automatically appear in the generated OpenAPI documentation.

3. Separate Models for Create, Update, and Response

Keep the codebase clean by defining distinct models for each operation:

from pydantic import BaseModel, Field, EmailStr
from datetime import datetime

class UserCreate(BaseModel):
    username: str = Field(min_length=3, max_length=30)
    email: EmailStr
    password: str = Field(min_length=8)

class UserUpdate(BaseModel):
    username: str | None = Field(default=None, min_length=3, max_length=30)
    email: EmailStr | None = None
    bio: str | None = Field(default=None, max_length=500)

class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    bio: str | None
    created_at: datetime
    model_config = ConfigDict(from_attributes=True)

When updating, use model_dump(exclude_unset=True) so only the fields sent by the client are applied:

update_data = data.model_dump(exclude_unset=True)
for key, value in update_data.items():
    setattr(user, key, value)

4. Cross‑Field Validation with @model_validator

Validate relationships between fields after individual field checks:

from pydantic import BaseModel, model_validator
from datetime import date

class DateRange(BaseModel):
    start_date: date
    end_date: date

    @model_validator(mode='after')
    def validate_date_range(self):
        if self.end_date <= self.start_date:
            raise ValueError('结束日期必须在开始日期之后')
        if (self.end_date - self.start_date).days > 365:
            raise ValueError('日期范围不能超过365天')
        return self

Use mode='before' for preprocessing, such as trimming strings or normalising email case.

5. Custom Error Messages for Front‑End Friendliness

FastAPI’s default 422 response is technically correct but hard for UI developers to consume. Override the exception handler:

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def custom_validation_handler(request: Request, exc: RequestValidationError):
    errors = {}
    for error in exc.errors():
        field = error['loc'][-1] if error['loc'] else 'unknown'
        errors[field] = error['msg']
    return JSONResponse(status_code=422, content={"success": False, "message": "校验失败", "errors": errors})

The front‑end now receives a clean map of field names to human‑readable messages.

6. Reusable Field Types to Eliminate Duplication

Define custom annotated types once and reuse them across models:

from typing import Annotated
from pydantic import Field, AfterValidator

def validate_phone(value: str) -> str:
    cleaned = ''.join(c for c in value if c.isdigit() or c == '+')
    if not (10 <= len(cleaned) <= 15):
        raise ValueError('手机号必须是10-15位数字')
    return cleaned

def validate_slug(value: str) -> str:
    import re
    if not re.match(r'^[a-z0-9]+(?:-[a-z0-9]+)*$', value):
        raise ValueError('slug必须是小写字母数字，单词间用连字符连接')
    return value

def validate_currency_code(value: str) -> str:
    valid = {'USD', 'EUR', 'GBP', 'JPY', 'AUD', 'CAD', 'CNY'}
    upper = value.upper()
    if upper not in valid:
        raise ValueError(f'币种必须是以下之一: {', '.join(sorted(valid))}')
    return upper

PhoneNumber = Annotated[str, AfterValidator(validate_phone)]
Slug = Annotated[str, Field(min_length=1, max_length=100), AfterValidator(validate_slug)]
CurrencyCode = Annotated[str, AfterValidator(validate_currency_code)]

class UserProfile(BaseModel):
    phone: PhoneNumber
    website_slug: Slug

class Payment(BaseModel):
    amount: float = Field(gt=0)
    currency: CurrencyCode

7. Forbid Extra Fields to Prevent Dirty Data

Configure the model to reject any keys not explicitly declared:

from pydantic import BaseModel, ConfigDict

class SecureUserCreate(BaseModel):
    model_config = ConfigDict(extra='forbid')
    username: str
    email: str
    password: str

# Passing an unexpected field raises ValidationError
SecureUserCreate(username="alice", email="[email protected]", password="12345678", is_admin=True)

8. Nested Models for Complex JSON Structures

Model composition keeps large payloads manageable:

from pydantic import BaseModel, Field

class OrderItem(BaseModel):
    product_id: int
    quantity: int = Field(gt=0, le=100)
    unit_price: float = Field(gt=0)

class ShippingAddress(BaseModel):
    street: str = Field(min_length=5)
    city: str
    postal_code: str = Field(pattern=r'^\d{5}(-\d{4})?$')
    country: str = Field(min_length=2, max_length=2)

class CreateOrder(BaseModel):
    model_config = ConfigDict(extra='forbid')
    customer_id: int
    items: list[OrderItem] = Field(min_length=1, max_length=50)
    shipping: ShippingAddress
    notes: str | None = Field(default=None, max_length=500)

    @model_validator(mode='after')
    def validate_order(self):
        total = sum(item.quantity * item.unit_price for item in self.items)
        if total > 10000:
            raise ValueError(f'订单总金额 ${total:.2f} 超过最大限额 $10,000')
        return self

9. Computed Fields in Response Models

Use @computed_field to expose derived values without storing them in the database:

from pydantic import BaseModel, computed_field
from datetime import datetime, timezone

class OrderResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    items: list[OrderItem]
    created_at: datetime
    status: str

    @computed_field
    @property
    def total(self) -> float:
        return sum(item.quantity * item.unit_price for item in self.items)

    @computed_field
    @property
    def item_count(self) -> int:
        return sum(item.quantity for item in self.items)

    @computed_field
    @property
    def age_hours(self) -> float:
        delta = datetime.now(timezone.utc) - self.created_at
        return round(delta.total_seconds() / 3600, 1)

10. Discriminated Union Types for Polymorphic Payloads

When an endpoint must accept different payload shapes, use a union with a discriminator field:

from pydantic import BaseModel, Field
from typing import Literal, Union, Annotated

class EmailNotification(BaseModel):
    channel: Literal['email']
    email_address: str
    subject_prefix: str | None = None

class SlackNotification(BaseModel):
    channel: Literal['slack']
    webhook_url: str
    mention_users: list[str] = []

class SMSNotification(BaseModel):
    channel: Literal['sms']
    phone_number: str
    max_length: int = Field(default=160, le=500)

NotificationConfig = Annotated[
    Union[EmailNotification, SlackNotification, SMSNotification],
    Field(discriminator='channel')
]

class UpdateNotificationSettings(BaseModel):
    user_id: int
    notifications: list[NotificationConfig]

@app.put("/settings/notifications")
def update_notifications(data: UpdateNotificationSettings):
    for notification in data.notifications:
        match notification.channel:
            case 'email':
                setup_email(notification.email_address)
            case 'slack':
                setup_slack(notification.webhook_url)
            case 'sms':
                setup_sms(notification.phone_number)
    return {"updated": len(data.notifications)}

Without a discriminator, developers would need a sprawling model with many optional fields or manual if/else logic.

Conclusion

Pydantic forms the invisible skeleton of every FastAPI service. While many developers stop after defining a simple model, production‑grade APIs require strict validation, model separation, custom error handling, reusable types, computed fields, and discriminated unions. Applying these ten tricks moves validation from a hidden afterthought to a reliable first line of defense.

Core Takeaways

Strict mode ( ConfigDict(strict=True)) blocks automatic type conversion for sensitive fields.

Separate create, update, and response models; use exclude_unset=True for partial updates.

Cross‑field validation with @model_validator (use mode='before' for preprocessing, mode='after' for relationship checks).