Come si scrive la validazione personalizzata in Pydantic?

Question

Accepted Answer

Oltre ai vincoli integrati, Pydantic ti permette di scrivere **logica di validazione personalizzata** con field validator (validare un campo) e model validator (validare su più campi) — per regole che i vincoli semplici non riescono a esprimere. (La sintassi mostrata è per Pydantic v2.)

## Field validator — validare/trasformare un singolo campo

```python
from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    password: str

@field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("username must be alphanumeric")   # → a 422 error
        return v.lower()                                         # can also TRANSFORM the value
```

Un `@field_validator` esegue logica personalizzata su un campo: solleva `ValueError` per rifiutare input non valido (FastAPI lo trasforma in una risposta chiara 422), oppure restituisce un valore trasformato (ad es. normalizzazione in minuscolo).

## Model validator — validazione cross-field

```python
from pydantic import model_validator

class SignupForm(BaseModel):
    password: str
    confirm_password: str

@model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm_password:    # compare MULTIPLE fields
            raise ValueError("passwords do not match")
        return self
```

Un `@model_validator(mode="after")` viene eseguito dopo che tutti i campi sono stati validati, con accesso all'intero modello — usato per regole che coinvolgono **più campi** (ad es. confermare che le password corrispondono, o che una data di inizio precede una data di fine).

## La validazione integrata spesso basta all'inizio

```python
class Product(BaseModel):
    price: float = Field(gt=0)          # use Field constraints for simple rules
    sku: str = Field(pattern=r"^[A-Z]{3}-\d+$")
    email: EmailStr                      # specialized types for formats
# reach for custom validators only when constraints/types can't express the rule
```

Preferisci i vincoli `Field` e i tipi specializzati per regole semplici; usa validator personalizzati per la vera logica di business.

## Perché è importante

La validazione personalizzata in Pydantic è importante per applicare regole di business che vanno oltre semplici controlli di tipo e vincoli — e poiché la validazione è critica per **sicurezza e integrità dei dati**, la capacità di esprimere qualsiasi regola è preziosa. I **field validator** gestiscono la logica a livello di singolo campo (controlli di formato personalizzati, normalizzazione/trasformazione), mentre i **model validator** gestiscono la necessità comune di **validazione cross-field** (password corrispondenti, intervalli di date, requisiti condizionali) che le regole a livello di campo non riescono a esprimere.

I validator si integrano perfettamente con FastAPI — un `ValueError` sollevato diventa automaticamente una risposta chiara 422.

Capire quando usare vincoli/tipi integrati (per regole semplici) rispetto a validator personalizzati (per vera logica di business), e come differiscono i validator di campo rispetto a quelli di modello, ti permette di garantire che i dati in ingresso soddisfino pienamente i requisiti della tua applicazione, rendendo questa una conoscenza importante per costruire API robuste e corrette.