O que são modelos Pydantic no FastAPI?

Question

Accepted Answer

**Modelos Pydantic** são classes (subclasses de `BaseModel`) que definem a **estrutura, tipos e regras de validação** dos dados. FastAPI os usa em todos os lugares — para request bodies, response shapes e configurações — tornando-os o coração de seu design orientado por tipos.

## Definindo um modelo

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

Cada campo declara um tipo e restrições/padrões opcionais. Pydantic valida os dados contra essa definição e converte tipos quando faz sentido.

## Validação e parsing automáticos

```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 usado como um tipo de parâmetro, FastAPI analisa o corpo da solicitação JSON no modelo, **valida** cada campo e retorna um erro 422 estruturado listando exatamente o que está errado — tudo automático.

## O que Pydantic te oferece

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

## Uma única fonte de verdade

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

## Por que isso importa

Os modelos Pydantic são a base do FastAPI — é como você define e valida os dados que sua API aceita e retorna, e quase todos os recursos do FastAPI fluem através deles.

Entendê-los é essencial porque fornecem **validação** automática (crítica para segurança e robustez — nunca confiando em entrada bruta), parsing/coerção, serialização e suporte a editores, tudo a partir de uma única classe declarativa.

Eles servem como **uma única fonte de verdade**: um modelo impulsiona a validação da solicitação, a forma da resposta e a documentação gerada automaticamente.

Essa abordagem orientada por tipos, validada por padrão — obter validação robusta de entrada e mensagens de erro claras essencialmente de graça — é uma razão importante pela qual FastAPI é tão produtivo e seguro, tornando os modelos Pydantic conhecimento fundamental, essencial.