Como você escreve validação personalizada no Pydantic?

Question

Accepted Answer

Além das restrições integradas, o Pydantic permite que você escreva **lógica de validação personalizada** com field validators (validar um campo) e model validators (validar múltiplos campos) — para regras que restrições simples não conseguem expressar. (Sintaxe mostrada é Pydantic v2.)

## Field validators — validar/transformar um único 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
```

Um `@field_validator` executa lógica personalizada em um campo: lance `ValueError` para rejeitar entrada inválida (FastAPI a transforma em uma resposta clara 422), ou retorne um valor transformado (ex: normalizar para minúsculas).

## Model validators — validação entre campos

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

Um `@model_validator(mode="after")` executa após todos os campos serem validados, com acesso ao modelo inteiro — usado para regras envolvendo **múltiplos campos** (ex: confirmar que senhas correspondem, ou que uma data de início precede uma data de término).

## Validação integrada geralmente é suficiente primeiro

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

Prefira restrições `Field` e tipos especializados para regras simples; use validators personalizados para lógica de negócio genuína.

## Por que isso importa

A validação personalizada no Pydantic é importante para impor regras de negócio que vão além de verificações de tipo simples e restrições — e uma vez que validação é crítica para **segurança e integridade de dados**, ser capaz de expressar qualquer regra é valioso. **Field validators** lidam com lógica de campo único (verificações de formato personalizado, normalização/transformação), enquanto **model validators** lidam com a necessidade comum de **validação entre campos** (senhas correspondentes, intervalos de datas, requisitos condicionais) que regras ao nível do campo não conseguem expressar.

Os validators se integram perfeitamente com FastAPI — um `ValueError` lançado se torna uma resposta clara 422 automaticamente.

Entender quando usar restrições/tipos integrados (para regras simples) versus validators personalizados (para lógica de negócio real), e como field validators diferem de model validators, permite garantir que dados de entrada satisfaçam completamente os requisitos da sua aplicação, tornando esse conhecimento importante para construir APIs robustas e corretas.