Como você modela corpos de requisição aninhados e complexos?

Question

Accepted Answer

Modelos Pydantic podem **aninhar** — um campo de modelo pode ser outro modelo, uma lista de modelos ou tipos complexos — permitindo que FastAPI valide automaticamente JSON profundamente estruturado (objetos dentro de objetos, arrays de objetos).

## Modelos aninhados

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

Um campo de modelo tipado como outro modelo (ou `list[Model]`) é validado recursivamente — objetos aninhados e arrays de objetos são todos verificados contra seus schemas automaticamente.

## Tipos especiais e complexos

```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 lida com tipos ricos: enums (restringir a valores permitidos), `datetime` (analisa strings ISO), `HttpUrl`/`EmailStr` (validação de formato) e typed dicts/tuples — todos validados automaticamente.

## Wrappers genéricos / reutilizáveis

```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 que isso importa

As APIs do mundo real raramente lidam com dados planos — elas lidam com estruturas complexas e aninhadas (um usuário com um endereço e uma lista de pedidos, um pedido com itens de linha, objetos de configuração), e a capacidade do Pydantic de **aninhar modelos** torna a validação desses corpos de requisição profundamente estruturados sem esforço.

Entender que um campo de modelo pode ser outro modelo, uma lista de modelos ou um tipo rico — e que FastAPI **valida toda a estrutura aninhada recursivamente** e automaticamente — é importante para construir APIs que aceitam entrada realista e complexa com segurança.

O suporte a tipos ricos (enums para valores restritos, análise de `datetime`, validação de formato `HttpUrl`/`EmailStr`, coleções tipadas) garante ainda mais que dados complexos sejam corretos sem verificações manuais.

Saber como modelar corpos aninhados e complexos (e wrappers genéricos reutilizáveis para coisas como paginação) é conhecimento prático para construir APIs que lidam com os dados estruturados que aplicações reais exigem, com validação completa fornecida automaticamente — um ponto forte do design baseado em Pydantic do FastAPI.