Pydantic ya convierte y valida tipos declarados; los validadores personalizados deben cubrir reglas que el schema no expresa. field_validator trabaja con campos y model_validator evalúa el objeto completo.

from datetime import date
from typing import Self
from pydantic import BaseModel, field_validator, model_validator

class Periodo(BaseModel):
    inicio: date
    fim: date

    @field_validator("inicio", "fim", mode="before")
    @classmethod
    def limpar_data(cls, valor: object) -> object:
        return valor.strip() if isinstance(valor, str) else valor

    @model_validator(mode="after")
    def validar_ordem(self) -> Self:
        if self.fim < self.inicio:
            raise ValueError("fim deve ser posterior ao início")
        return self

El modo before recibe la entrada bruta y debe admitir cualquier objeto. El validador de modelo after recibe la instancia validada y devuelve self. El orden de fechas es una regla entre campos, por lo que pertenece al modelo.

Buenas prácticas

Mantén validadores determinísticos y sin llamadas de red o base de datos. Lanza ValueError con un mensaje útil que no exponga secretos. Evita mutar la entrada antes de fallar dentro de unions, pues otra rama puede recibir el objeto cambiado. Prueba casos válidos, límites y fallos.

Aplica estos validadores en el tutorial de FastAPI y separa configuración mediante Pydantic Settings.

La documentación oficial de validadores de Pydantic, consultada el 22 de julio de 2026, detalla la API y sus límites.