How do you write custom validation in Pydantic?

Question

Accepted Answer

Beyond built-in constraints, Pydantic lets you write **custom validation logic** with field validators (validate one field) and model validators (validate across multiple fields) — for rules that simple constraints can't express. (Syntax shown is Pydantic v2.)

## Field validators — validate/transform a single field

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

A `@field_validator` runs custom logic on a field: raise `ValueError` to reject invalid input (FastAPI turns it into a clear 422), or return a transformed value (e.g. normalizing to lowercase).

## Model validators — cross-field validation

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

A `@model_validator(mode="after")` runs after all fields are validated, with access to the whole model — used for rules involving **multiple fields** (e.g. confirming passwords match, or that a start date precedes an end date).

## Built-in validation often suffices first

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

Prefer `Field` constraints and specialized types for simple rules; use custom validators for genuine business logic.

## Why it matters

Custom Pydantic validation is important for enforcing business rules that go beyond simple type checks and constraints — and since validation is critical for **security and data integrity**, being able to express any rule is valuable. **Field validators** handle single-field logic (custom format checks, normalization/transformation), while **model validators** handle the common need for **cross-field validation** (passwords matching, date ranges, conditional requirements) that field-level rules can't express.

The validators integrate seamlessly with FastAPI — a raised `ValueError` becomes a clear 422 response automatically.

Understanding when to use built-in constraints/types (for simple rules) versus custom validators (for real business logic), and how field vs model validators differ, lets you ensure incoming data fully satisfies your application's requirements, making this important knowledge for building robust, correct APIs.