FastAPI Request Body and Pydantic Models

The shift from raw dictionaries to Pydantic models is the single biggest architectural upgrade FastAPI offers. In older frameworks, developers spent roughly 30% of their time writing 'defensive code'—checking if keys exist, verifying types, and manually parsing JSON.

At TheCodeForge, we use Pydantic models as our 'Source of Truth.' Because FastAPI uses these models to generate OpenAPI (Swagger) documentation, your code and your docs can never get out of sync. This 'Schema-First' approach ensures that your core logic only ever interacts with guaranteed, high-integrity Python objects.

But here's the part most tutorials skip: Pydantic models aren't just validation—they're the contract between your mobile app and your backend. Get that contract wrong, and you're debugging silent data corruption at 3 AM.

Defining a Pydantic Model with Type Coercion

A Pydantic model is not just a validator; it's a data transformer. If a client sends a numeric string like "99.99" for a field typed as float, Pydantic will 'coerce' it into a proper Python float automatically.

But automatic coercion is a double-edged sword. It saves you from writing parsing code for every field, but it can mask subtle bugs. For example, an empty string "" coerces to 0.0 for a float field — that silent conversion might violate business rules. Always pair broad types with constraints like Field(gt=0)` to catch edge cases early.

from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import Optional

app = FastAPI()

class ForgeItem(BaseModel):
    name: str
    price: float = Field(gt=0, description="Unit price in USD")
    is_active: bool = True
    description: Optional[str] = None

@app.post('/forge/items')
async def create_artifact(item: ForgeItem):
    return {"msg": "Success", "data": item.model_dump()}

Handling Nested Models and Collections

APIs are rarely flat. Pydantic handles recursive validation of nested objects and lists with ease. If even one deeply nested field fails validation, the entire request is rejected, maintaining data integrity.

This recursive validation is key to building self-documenting APIs. Each nested model becomes a sub-schema in OpenAPI, giving frontend teams precise contracts. Performance is rarely an issue: validating a deeply nested object with 3 levels of nesting takes under 100µs. The real cost comes from running @field_validator on every nested field — avoid heavy computation in validators for nested models.

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()

class Address(BaseModel):
    street: str
    city: str
    zip_code: str

class ForgeUser(BaseModel):
    username: str
    email: EmailStr
    address: Address
    tags: list[str] = []

@app.post('/forge/users')
async def register_user(user: ForgeUser):
    return {"status": "registered", "user": user}

Advanced Logic with Field Validators

Sometimes basic constraints like min_length aren't enough. Use @field_validator for complex cross-field validation or custom business rules that require Python logic.

Validators run after type coercion, so the input is already the correct type. They can modify the value (e.g., strip whitespace, convert to uppercase) or raise a ValueError with a custom message. That message is returned directly in the 422 error, which is far better than a generic 'field required' error.

One gotcha: validators are class methods by convention. Use @classmethod and .field_validator (Pydantic v2) or @validator (v1). If you need to validate multiple fields together, use @model_validator (v2) or @root_validator (v1).

from fastapi import FastAPI
from pydantic import BaseModel, Field, field_validator

app = FastAPI()

class ForgeProduct(BaseModel):
    sku: str = Field(min_length=8, max_length=12)
    inventory_count: int = Field(ge=0)
    category: str

    @field_validator('sku')
    @classmethod
    def sku_must_be_uppercase(cls, v: str) -> str:
        if not v.isupper():
            raise ValueError('SKU must be all uppercase for tracking purposes')
        return v

@app.post('/forge/inventory')
async def update_stock(product: ForgeProduct):
    return product

Request Body with Multiple Sources (Path, Query, and Body)

FastAPI allows mixing path parameters, query parameters, and a Pydantic body in a single endpoint. The router determines which is which based on type hints and parameter locations. When you define a parameter as a Pydantic model without a default, it becomes the request body. But if you also need query parameters that overlap with model fields, you must disambiguate using Query() or Path().

A common mistake: defining a model field with the same name as a path parameter — FastAPI will treat the path parameter as the model field and the request body becomes invalid. Use Field(alias='...') to separate them.

from fastapi import FastAPI, Query, Path
from pydantic import BaseModel

app = FastAPI()

class OrderUpdate(BaseModel):
    status: str
    note: str = ""

@app.put('/orders/{order_id}')
async def update_order(
    order_id: str = Path(..., description='The order ID'),
    update: OrderUpdate = None,
    dry_run: bool = Query(False)
):
    if dry_run:
        return {"would_update": update.model_dump()}
    # actual update logic
    return {"updated": order_id}

Using Pydantic Models for Responses — Security and Contract

Pydantic models aren't just for request bodies. Use response_model in the decorator to define the shape of your API responses. This automatically filters out fields not in the response model, preventing accidental data leaks (like password hashes).

FastAPI will serialize the response model to JSON, respecting Field(alias=...) and excluding unset fields. It also generates the OpenAPI response schema, so your docs stay in sync.

A nuance: if your endpoint returns a Response object directly, response_model is ignored. Also, when using response_model_exclude_unset=True, only fields that were set in your code are returned — useful for PATCH responses.

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()

class UserIn(BaseModel):
    username: str
    email: EmailStr
    password: str  # will be filtered from response

class UserOut(BaseModel):
    username: str
    email: EmailStr
    is_active: bool = True

@app.post('/users', response_model=UserOut)
async def create_user(user: UserIn):
    # hash password, store in DB
    hashed = hash_password(user.password)
    db_user = store_user(user.username, user.email, hashed)
    # return only UserOut fields — password is excluded
    return UserOut(username=db_user.username, email=db_user.email)

Frequently Asked Questions