Hoe model je geneste en complexe request bodies?

Question

Accepted Answer

Pydantic-modellen kunnen **genest** worden — een modelveld kan zelf een ander model zijn, een lijst van modellen, of complexe typen — waardoor FastAPI diep gestructureerde JSON (objecten in objecten, arrays van objecten) automatisch kan valideren.

## Geneste modellen

```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"] }
```

Een modelveld dat als een ander model (of `list[Model]`) is getypeerd, wordt recursief gevalideerd — geneste objecten en arrays van objecten worden allemaal automatisch tegen hun schema's gecontroleerd.

## Complexe en speciale typen

```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 ondersteunt rijke typen: enums (beperken tot toegestane waarden), `datetime` (parseert ISO-strings), `HttpUrl`/`EmailStr` (formaatvalidatie), en getypeerde dicts/tuples — allemaal automatisch gevalideerd.

## Generieke / herbruikbare 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 }
```

## Waarom het belangrijk is

Real-world API's hebben zelden met platte gegevens te maken — ze verwerken complexe, geneste structuren (een gebruiker met een adres en een lijst met bestellingen, een bestelling met regelitems, configuratieobjecten), en Pydantic's vermogen om **modellen te nesten** maakt validatie van deze diep gestructureerde request bodies moeiteloos.

Begrijpen dat een modelveld een ander model kan zijn, een lijst van modellen, of een rijkelijk type — en dat FastAPI **de gehele geneste structuur recursief en automatisch valideert** — is belangrijk voor het bouwen van API's die realistieke, complexe input veilig accepteren.

De ondersteuning voor rijke typen (enums voor beperkte waarden, `datetime` parsing, `HttpUrl`/`EmailStr` formaatvalidatie, getypeerde collecties) zorgt er verder voor dat complexe gegevens correct zijn zonder handmatige controles.

Weten hoe je geneste en complexe bodies modelleert (en herbruikbare generieke wrappers voor zaken als paginering) is praktische kennis voor het bouwen van API's die de gestructureerde gegevens verwerken die echte applicaties nodig hebben, met volledige validatie die automatisch wordt geleverd — een kernsterkte van FastAPI's op Pydantic gebaseerde ontwerp.