¿Cómo modelar cuerpos de solicitudes anidados y complejos?

Question

Accepted Answer

Los modelos de Pydantic pueden **anidarse** — un campo de modelo puede ser otro modelo, una lista de modelos o tipos complejos — lo que permite que FastAPI valide automáticamente JSON profundamente estructurado (objetos dentro de objetos, arrays de objetos).

## Modelos anidados

```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 de modelo escrito como otro modelo (o `list[Model]`) se valida recursivamente — los objetos anidados y los arrays de objetos se verifican automáticamente contra sus esquemas.

## Tipos complejos y especiales

```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 maneja tipos ricos: enums (restringir a valores permitidos), `datetime` (analiza cadenas ISO), `HttpUrl`/`EmailStr` (validación de formato) y dicts/tuplas tipados — todo se valida automáticamente.

## Envoltorios genéricos / reutilizables

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

## Por qué es importante

Las API del mundo real rara vez tratan con datos planos — manejan estructuras complejas y anidadas (un usuario con una dirección y una lista de pedidos, un pedido con elementos de línea, objetos de configuración), y la capacidad de Pydantic para **anidar modelos** hace que validar cuerpos de solicitud profundamente estructurados sea sin esfuerzo.

Entender que un campo de modelo puede ser otro modelo, una lista de modelos o un tipo rico — y que FastAPI **valida recursivamente toda la estructura anidada de forma automática** — es importante para construir API que acepten entradas realistas y complejas de manera segura.

La compatibilidad con tipos ricos (enums para valores restringidos, análisis de `datetime`, validación de formato `HttpUrl`/`EmailStr`, colecciones tipadas) además asegura que los datos complejos sean correctos sin comprobaciones manuales.

Saber cómo modelar cuerpos anidados y complejos (y envoltorios genéricos reutilizables para cosas como paginación) es conocimiento práctico para construir API que manejen los datos estructurados que requieren las aplicaciones reales, con validación completa proporcionada automáticamente — una fortaleza clave del diseño basado en Pydantic de FastAPI.