Comment modélisez-vous les corps de requête imbriqués et complexes ?

Question

Accepted Answer

Les modèles Pydantic peuvent **s'imbriquer** — un champ de modèle peut être un autre modèle, une liste de modèles ou des types complexes — permettant à FastAPI de valider automatiquement des JSON profondément structurés (objets dans des objets, tableaux d'objets).

## Modèles imbriqués

```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 champ de modèle typé comme un autre modèle (ou `list[Model]`) est validé récursivement — les objets imbriqués et les tableaux d'objets sont tous vérifiés par rapport à leurs schémas automatiquement.

## Types complexes et spéciaux

```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 gère les types riches : enums (restrictor aux valeurs autorisées), `datetime` (analyse les chaînes ISO), `HttpUrl`/`EmailStr` (validation du format) et typed dicts/tuples — tous validés automatiquement.

## Wrappers génériques / réutilisables

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

## Pourquoi c'est important

Les API du monde réel traitent rarement des données plates — elles gèrent des structures complexes et imbriquées (un utilisateur avec une adresse et une liste de commandes, une commande avec des lignes d'article, des objets de configuration), et la capacité de Pydantic à **imbriquer les modèles** rend la validation de ces corps de requête profondément structurés simple.

Comprendre qu'un champ de modèle peut être un autre modèle, une liste de modèles ou un type riche — et que FastAPI **valide la structure imbriquée entière récursivement** et automatiquement — est important pour construire des API qui acceptent des entrées réalistes et complexes de manière sûre.

Le support des types riches (enums pour les valeurs contraintes, analyse `datetime`, validation du format `HttpUrl`/`EmailStr`, collections typées) garantit en outre que les données complexes sont correctes sans vérifications manuelles.

Savoir comment modéliser les corps imbriqués et complexes (et les wrappers génériques réutilisables pour des choses comme la pagination) est une connaissance pratique pour construire des API qui gèrent les données structurées que les applications réelles exigent, avec validation complète fournie automatiquement — une force clé de la conception de FastAPI basée sur Pydantic.