FastAPI Pydantic Models: A Deep Dive

What and Why

FastAPI rests on Pydantic. Every request body, query model, and response is a Pydantic model under the hood. Knowing Pydantic well means cleaner code, better errors, and free OpenAPI docs.

Mental Model

Pydantic takes raw input, runs it through field validators, and produces a typed object. If anything fails, it raises a ValidationError with structured detail, which FastAPI turns into a 422 response.

HTTP body (JSON)
   |
   v
Parse JSON -> dict
   |
   v
Pydantic model
- coerce types
- run field validators
- run model validators
   |
   v
Typed object passed to your endpoint
   |
   v
Endpoint returns model or dict -> serialized JSON

Hands-on Example

Start with a request and response pair.

from datetime import datetime
from typing import Annotated
from pydantic import BaseModel, Field, EmailStr, field_validator
from fastapi import FastAPI

app = FastAPI()

class UserCreate(BaseModel):
    email: EmailStr
    password: Annotated[str, Field(min_length=8, max_length=128)]
    name: Annotated[str, Field(min_length=1, max_length=80)]

    @field_validator("password")
    @classmethod
    def must_have_digit(cls, v: str) -> str:
        if not any(c.isdigit() for c in v):
            raise ValueError("password must include a digit")
        return v

class UserOut(BaseModel):
    id: int
    email: EmailStr
    name: str
    created_at: datetime

@app.post("/users", response_model=UserOut)
def create_user(payload: UserCreate) -> UserOut:
    # pretend we persisted and got an id and timestamp
    return UserOut(id=1, email=payload.email, name=payload.name,
                   created_at=datetime.utcnow())

Notice the separation. UserCreate accepts what the client sends. UserOut controls what we return. Never reuse the same model for both. Doing so leaks fields like password or internal ids.

Nested models compose naturally.

class Address(BaseModel):
    street: str
    city: str
    country: str = "US"

class OrderCreate(BaseModel):
    items: list[str]
    shipping: Address

Aliases help when JSON uses camelCase but Python uses snake_case.

from pydantic import ConfigDict

class Product(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    product_id: int = Field(alias="productId")
    display_name: str = Field(alias="displayName")

Model-wide validation runs after all fields pass.

from pydantic import model_validator

class Range(BaseModel):
    low: int
    high: int

    @model_validator(mode="after")
    def check_order(self):
        if self.low > self.high:
            raise ValueError("low must be <= high")
        return self

Settings give you typed configuration from env vars.

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    debug: bool = False

    model_config = {"env_file": ".env"}

settings = Settings()

Common Pitfalls

• Reusing one model for input and output. Use separate UserCreate, UserUpdate, UserOut.
• Forgetting that Pydantic v2 changed validator decorators. Use field_validator and model_validator.
• Trusting client-supplied ids. Use Annotated[str, Field(...)] to constrain length, then map to your DB id server-side.
• Overusing Optional. Optional[X] means “can be None”, not “missing.” Use X | None = None thoughtfully.
• Returning ORM rows directly. Either define from_attributes=True or build the output model explicitly.

Practical Tips

• Use EmailStr, HttpUrl, UUID, and datetime to get parsing for free.
• Reach for Annotated[T, Field(...)] so types and constraints stay together.
• Add examples via Field(..., examples=["jane@acme.com"]) to enrich the OpenAPI docs.
• Keep validators pure. They should never call the database or make HTTP requests.
• Compose response models with model_copy(update={...}) rather than mutating fields.

Wrap-up

Pydantic is more than schema validation. It is a tool for designing the boundary of your API. When you take time to model requests and responses as separate types with sharp constraints, your endpoints become tiny adapters and your docs become a living spec. Lean into validators for the rules that matter, and let Pydantic carry the rest.