Cosa sono i modelli Pydantic in FastAPI?

Question

Accepted Answer

**I modelli Pydantic** sono classi (che ereditano da `BaseModel`) che definiscono la **struttura, i tipi e le regole di validazione** dei dati. FastAPI li utilizza ovunque — per i corpi delle richieste, le forme delle risposte e le impostazioni — rendendoli il cuore del suo design basato sui tipi.

## Definire un modello

```python
from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    name: str
    email: EmailStr                          # validates email format
    age: int = Field(ge=0, le=120)            # constraint: 0 <= age <= 120
    is_active: bool = True                    # default value
    tags: list[str] = []                      # typed list with a default
```

Ogni campo dichiara un tipo e vincoli/valori predefiniti opzionali. Pydantic valida i dati rispetto a questa definizione e converte i tipi dove sensato.

## Validazione e parsing automatici

```python
@app.post("/users")
def create_user(user: User):                  # FastAPI builds & validates a User from the body
    return user                               # already validated here
# valid JSON → a typed User object; invalid → automatic 422 with field-level errors
```

Quando utilizzato come tipo di parametro, FastAPI analizza il corpo della richiesta JSON nel modello, **validando** ogni campo e restituendo un errore strutturato 422 che elenca esattamente cosa non va — tutto automatico.

## Cosa ti fornisce Pydantic

```text
✓ Validation — type checks + constraints (lengths, ranges, formats), clear errors
✓ Parsing/coercion — "5" → 5, ISO string → datetime, etc.
✓ Serialization — model.model_dump() / model_dump_json() → dict/JSON
✓ Editor support — full autocomplete & type checking on model attributes
✓ Self-documenting — the model defines the schema used in the auto-generated docs
```

## Una singola fonte di verità

```text
One Pydantic model drives: request validation, the response schema, the OpenAPI docs,
and typed access in your code → define the data shape ONCE.
```

## Perché è importante

I modelli Pydantic sono la pietra angolare di FastAPI — sono il modo in cui definisci e validi i dati che la tua API accetta e restituisce, e quasi ogni funzionalità di FastAPI passa attraverso di essi.

Comprenderli è essenziale perché forniscono **validazione** automatica (critica per la sicurezza e la robustezza — non fidandosi mai dell'input grezzo), parsing/coercizione, serializzazione e supporto dell'editor, il tutto da una singola classe dichiarativa.

Servono come **singola fonte di verità**: un modello guida la validazione delle richieste, la forma della risposta e la documentazione generata automaticamente.

Questo approccio basato sui tipi, validate-by-default — ottenendo validazione robusta dell'input e messaggi di errore chiari essenzialmente gratuitamente — è una ragione importante per cui FastAPI è così produttivo e sicuro, rendendo i modelli Pydantic conoscenze fondamentali e imprescindibili.