Come modelli request body annidati e complessi?

Question

Accepted Answer

I modelli Pydantic possono **annidare** — un campo di un modello può essere a sua volta un altro modello, una lista di modelli, o tipi complessi — permettendo a FastAPI di validare automaticamente JSON profondamente strutturato (oggetti dentro oggetti, array di oggetti).

## Modelli annidati

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

Un campo di modello tipizzato come un altro modello (o `list[Model]`) viene validato ricorsivamente — gli oggetti annidati e gli array di oggetti sono tutti controllati rispetto ai loro schemi automaticamente.

## Tipi complessi e speciali

```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 gestisce tipi ricchi: enum (limitare ai valori consentiti), `datetime` (analizza stringhe ISO), `HttpUrl`/`EmailStr` (validazione del formato), e dict/tuple tipizzati — tutti validati automaticamente.

## Wrapper generici / riutilizzabili

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

## Perché è importante

Le API del mondo reale raramente gestiscono dati piatti — gestiscono strutture complesse e annidate (un utente con un indirizzo e una lista di ordini, un ordine con righe, oggetti di configurazione), e la capacità di Pydantic di **annidare modelli** rende la validazione di questi request body profondamente strutturati senza sforzo.

Capire che un campo di modello può essere un altro modello, una lista di modelli, o un tipo ricco — e che FastAPI **valida l'intera struttura annidata ricorsivamente** e automaticamente — è importante per costruire API che accettano input realistici e complessi in modo sicuro.

Il supporto dei tipi ricchi (enum per valori vincolati, analisi `datetime`, validazione del formato `HttpUrl`/`EmailStr`, collezioni tipizzate) garantisce inoltre che i dati complessi siano corretti senza controlli manuali.

Sapere come modellare body annidati e complessi (e wrapper generici riutilizzabili per cose come la paginazione) è una conoscenza pratica per costruire API che gestiscono i dati strutturati che le applicazioni reali richiedono, con validazione completa fornita automaticamente — un punto di forza fondamentale del design di FastAPI basato su Pydantic.