How do you model nested and complex request bodies?

Question

Accepted Answer

Pydantic models can **nest** — a model field can itself be another model, a list of models, or complex types — letting FastAPI validate deeply structured JSON (objects within objects, arrays of objects) automatically.

## Nested models

```python
from pydantic import BaseModel

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

class User(BaseModel):
    name: str
    address: Address                    # a NESTED model
    tags: list[str] = []                # a list of strings
    addresses: list[Address] = []       # a list of NESTED models

@app.post("/users")
def create(user: User):                  # validates the WHOLE nested structure
    return user
```

```json
// FastAPI validates this entire structure, including the nested address:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

A model field typed as another model (or `list[Model]`) is validated recursively — nested objects and arrays of objects are all checked against their schemas automatically.

## Complex and special types

```python
from pydantic import BaseModel, HttpUrl, EmailStr
from datetime import datetime
from enum import Enum

class Status(str, Enum):                 # enums constrain to allowed values
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # validates URL format
    email: EmailStr                       # validates email format
    created: datetime                     # parses ISO 8601 strings → datetime
    status: Status                        # must be one of the enum values
    metadata: dict[str, int]              # typed dict
    coordinates: tuple[float, float]      # typed tuple
```

Pydantic handles rich types: enums (restrict to allowed values), `datetime` (parses ISO strings), `HttpUrl`/`EmailStr` (format validation), and typed dicts/tuples — all validated automatically.

## Generic / reusable wrappers

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # a reusable generic response wrapper
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## Why it matters

Real-world APIs rarely deal with flat data — they handle complex, nested structures (a user with an address and a list of orders, an order with line items, configuration objects), and Pydantic's ability to **nest models** makes validating these deeply structured request bodies effortless.

Understanding that a model field can be another model, a list of models, or a rich type — and that FastAPI **validates the entire nested structure recursively** and automatically — is important for building APIs that accept realistic, complex input safely.

The rich type support (enums for constrained values, `datetime` parsing, `HttpUrl`/`EmailStr` format validation, typed collections) further ensures complex data is correct without manual checks.

Knowing how to model nested and complex bodies (and reusable generic wrappers for things like pagination) is practical knowledge for building APIs that handle the structured data real applications require, with full validation provided automatically — a key strength of FastAPI's Pydantic-based design.