¿Cómo escribes validación personalizada en Pydantic?

Question

Accepted Answer

Más allá de las restricciones integradas, Pydantic te permite escribir **lógica de validación personalizada** con validadores de campo (valida un campo) y validadores de modelo (valida múltiples campos) — para reglas que las restricciones simples no pueden expresar. (La sintaxis mostrada es Pydantic v2.)

## Validadores de campo — valida/transforma un ú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
```

Un `@field_validator` ejecuta lógica personalizada en un campo: lanza `ValueError` para rechazar entrada inválida (FastAPI la convierte en una respuesta 422 clara), o devuelve un valor transformado (p. ej. normalizar a minúsculas).

## Validadores de modelo — validación 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
```

Un `@model_validator(mode="after")` se ejecuta después de que todos los campos sean validados, con acceso a todo el modelo — se usa para reglas que involucran **múltiples campos** (p. ej. confirmar que las contraseñas coincidan, o que una fecha de inicio preceda a una fecha de fin).

## La validación integrada a menudo es suficiente primero

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

Prefieres restricciones de `Field` y tipos especializados para reglas simples; usa validadores personalizados para lógica de negocio genuina.

## Por qué es importante

La validación personalizada de Pydantic es importante para hacer cumplir reglas de negocio que van más allá de simples comprobaciones de tipo y restricciones — y como la validación es crítica para **seguridad e integridad de datos**, poder expresar cualquier regla es valioso. **Los validadores de campo** manejan lógica de un único campo (comprobaciones de formato personalizado, normalización/transformación), mientras que **los validadores de modelo** manejan la necesidad común de **validación entre campos** (contraseñas coincidentes, rangos de fechas, requisitos condicionales) que las reglas a nivel de campo no pueden expresar.

Los validadores se integran sin problemas con FastAPI — un `ValueError` lanzado se convierte automáticamente en una respuesta 422 clara.

Entender cuándo usar restricciones/tipos integrados (para reglas simples) versus validadores personalizados (para lógica de negocio real), y cómo difieren los validadores de campo versus modelo, te permite garantizar que los datos entrantes satisfagan completamente los requisitos de tu aplicación, haciendo este conocimiento importante para construir APIs robustas y correctas.