Custom validators in FastAPI - Deep Dive

Overview - Custom validators

What is it?

Custom validators in FastAPI let you check and control the data your app receives. They are functions or methods that run automatically to confirm data is correct before your app uses it. This helps catch mistakes early and keeps your app safe and reliable. You write these validators to add rules beyond the basic types FastAPI checks by default.

Why it matters

Without custom validators, your app might accept wrong or harmful data, causing bugs or security problems. Custom validators let you enforce specific rules, like password strength or date ranges, making your app behave exactly as you want. This improves user experience and prevents errors that could be hard to find later.

Where it fits

Before learning custom validators, you should understand FastAPI basics, especially how it uses Pydantic models for data validation. After mastering custom validators, you can explore advanced data handling like dependency injection, security features, and error handling in FastAPI.

Mental Model

Core Idea

Custom validators are special checks you add to your data models that automatically run to confirm data meets your exact rules before your app uses it.

Think of it like...

It's like a security guard at a club entrance who checks not just your ID but also your dress code and behavior before letting you in.

┌─────────────────────────────┐
│ Incoming Data               │
└─────────────┬───────────────┘
              │
      ┌───────▼────────┐
      │ Pydantic Model  │
      │ (Basic Checks)  │
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │ Custom Validator│
      │ (Extra Rules)   │
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │ Validated Data  │
      └────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Pydantic Models Basics

Concept: Learn how FastAPI uses Pydantic models to define and validate data automatically.

In FastAPI, you define data shapes using Pydantic models. For example, a User model with name and age fields. FastAPI checks incoming data matches these types and required fields before your code runs.

Result

FastAPI rejects requests with missing or wrong-type data, returning clear error messages.

Understanding Pydantic models is key because custom validators build on this automatic data checking.

2

Foundation

Basic Field Validation with Pydantic

Concept: Learn how to add simple validation rules like minimum length or value using Pydantic field parameters.

You can add rules like min_length=3 for strings or ge=0 for numbers directly in model fields. For example, age: int = Field(..., ge=18) means age must be at least 18.

Result

FastAPI rejects data that breaks these simple rules with helpful errors.

Knowing these built-in validations helps you see when you need custom validators for more complex rules.

3

Intermediate

Creating Custom Validator Methods

🤔Before reading on: do you think custom validators are standalone functions or methods inside models? Commit to your answer.

Concept: Learn how to write methods inside Pydantic models that run extra checks on fields or the whole model.

Use the @validator decorator on a method inside your model class. This method receives the field value and can raise errors if the value is invalid. For example, check a username doesn't contain spaces.

Result

FastAPI runs your custom method automatically during validation and rejects bad data with your custom error message.

Understanding that validators are methods inside models clarifies how validation stays organized and close to the data.

4

Intermediate

Validating Multiple Fields Together

🤔Before reading on: do you think you can validate multiple fields at once with a single validator? Commit to yes or no.

Concept: Learn to write validators that check relationships between multiple fields in the same model.

Use @root_validator decorator to create a method that receives all fields as a dictionary. You can check conditions like 'start date must be before end date' and raise errors if not.

Result

FastAPI enforces complex rules involving multiple fields, improving data correctness.

Knowing how to validate multiple fields together lets you enforce real-world rules that single-field checks can't handle.

5

Intermediate

Using Custom Validators with External Functions

Concept: Learn how to call external functions from validators to keep code clean and reusable.

Inside your validator method, you can call any Python function to perform checks, like password strength or email format. This separates logic and makes testing easier.

Result

Your validation logic stays organized and can be reused across models or projects.

Separating validation logic into functions improves maintainability and clarity in larger projects.

6

Advanced

Handling Asynchronous Validation Needs

🤔Before reading on: do you think Pydantic validators support async functions? Commit to yes or no.

Concept: Learn the limitations of Pydantic validators regarding async code and how to handle async validation in FastAPI.

Pydantic validators do not support async functions directly. For async checks like database lookups, perform validation inside FastAPI dependencies or route logic after initial validation.

Result

You avoid blocking your app and keep validation efficient by separating async checks from Pydantic validators.

Knowing where async validation fits prevents common mistakes that cause slow or broken apps.

7

Expert

Custom Validators Internals and Performance

🤔Before reading on: do you think custom validators run once or multiple times during request handling? Commit to your answer.

Concept: Understand how FastAPI and Pydantic run validators during model creation and the impact on performance and error handling.

Validators run every time a model instance is created, which happens on each request with input data. Complex validators can slow down your app if not optimized. Also, validators run in order, so errors from earlier validators stop later ones.

Result

You write efficient validators and order them to catch errors early, improving app speed and user feedback.

Understanding validator execution order and cost helps you design fast, user-friendly validation flows.

Under the Hood

When FastAPI receives data, it uses Pydantic to create model instances. Pydantic runs built-in type checks first, then calls any custom validator methods decorated with @validator or @root_validator. These methods receive the data, can modify it, or raise errors. If any validator fails, Pydantic raises a ValidationError, which FastAPI catches and turns into a clear HTTP error response.

Why designed this way?

Pydantic was designed to separate data parsing and validation from business logic, making validation declarative and reusable. Custom validators as methods keep validation close to data definitions, improving readability and maintainability. This design avoids mixing validation code throughout the app and leverages Python's class system for organization.

┌───────────────┐
│ Incoming Data │
└───────┬───────┘
        │
┌───────▼─────────────┐
│ Pydantic Model Init  │
│ (Type Checks)       │
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ Custom Validators   │
│ (@validator methods)│
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ Validation Success  │
│ or ValidationError  │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think Pydantic validators can be async functions? Commit to yes or no.

Common Belief: Many believe you can write async custom validators directly in Pydantic models.

Reality: Pydantic validators must be synchronous; async validators are not supported and will cause errors or unexpected behavior.

Why it matters: Trying to use async validators causes runtime errors or silent failures, leading to broken validation and security risks.

Quick: Do you think custom validators run only once per app start? Commit to yes or no.

Common Belief: Some think validators run once when the app starts and then cache results.

Reality: Validators run every time a model instance is created, usually on every request with new data.

Why it matters: Assuming one-time execution can lead to slow apps if validators do expensive work without caching.

Quick: Do you think you can modify other fields from a single-field validator? Commit to yes or no.

Common Belief: People often believe a validator on one field can change other fields in the model.

Reality: Single-field validators only receive and return the value of that field; to validate or modify multiple fields together, use root validators.

Why it matters: Misusing single-field validators for multi-field logic causes bugs and unexpected validation errors.

Quick: Do you think custom validators replace all error handling in FastAPI? Commit to yes or no.

Common Belief: Some assume custom validators handle every kind of input error and no other error handling is needed.

Reality: Custom validators only check data validity; other errors like server issues or authentication require separate handling.

Why it matters: Relying solely on validators can leave your app vulnerable to other error types, causing crashes or bad user experience.

Expert Zone

1

Custom validators run in the order they are defined, so placing cheaper or more common checks first improves performance and error clarity.

2

Validators can modify and return the value, allowing data normalization (like trimming spaces) before your app uses it.

3

Root validators run after all field validators, so they see the final state of all fields, enabling complex cross-field logic.

When NOT to use

Avoid custom validators for asynchronous checks like database lookups; instead, use FastAPI dependencies or route-level logic. Also, do not use validators for business logic unrelated to data correctness; keep validation focused and separate.

Production Patterns

In real apps, custom validators enforce security rules (password strength), data consistency (date ranges), and format normalization (lowercasing emails). Validators are combined with FastAPI dependencies for async checks and error handling middleware for robust APIs.

Connections

Data Validation in Web Forms

Custom validators in FastAPI serve the same purpose as client-side form validation but run on the server side.

Understanding server-side validation complements client-side checks, ensuring data integrity even if users bypass browser controls.

Design by Contract (Software Engineering)

Custom validators act like contracts that specify what data is allowed, similar to preconditions in design by contract.

Seeing validation as enforcing contracts helps write clearer, safer code that fails early with clear reasons.

Quality Control in Manufacturing

Custom validators are like quality inspectors checking products against standards before shipping.

This connection shows how validation prevents defects from reaching users, improving overall product reliability.

Common Pitfalls

#1 Trying to write async validators inside Pydantic models.

Wrong approach:

from pydantic import BaseModel, validator

class User(BaseModel):
email: str

@validator('email')
async def check_email(cls, v):
# async call to check email uniqueness
return v

Correct approach:

from pydantic import BaseModel, validator

class User(BaseModel):
email: str

@validator('email')
def check_email(cls, v):
# synchronous checks only
return v

# Perform async checks in FastAPI route or dependency

Root cause:

Misunderstanding that Pydantic validators support async functions, which they do not.

#2 Using single-field validators to check multiple fields.

Wrong approach:

from pydantic import BaseModel, validator

class Event(BaseModel):
start: int
end: int

@validator('start')
def check_start_before_end(cls, v, values):
if 'end' in values and v >= values['end']:
raise ValueError('start must be before end')
return v

Correct approach:

from pydantic import BaseModel, root_validator

class Event(BaseModel):
start: int
end: int

@root_validator
def check_start_before_end(cls, values):
start = values.get('start')
end = values.get('end')
if start is not None and end is not None and start >= end:
raise ValueError('start must be before end')
return values

Root cause:

Confusing single-field validators with root validators and their capabilities.

#3 Performing expensive operations inside validators without caching.

Wrong approach:

from pydantic import BaseModel, validator

class User(BaseModel):
username: str

@validator('username')
def check_username_unique(cls, v):
# expensive DB call every time
if not is_unique(v):
raise ValueError('username taken')
return v

Correct approach:

# Perform uniqueness check in route or dependency with caching
# Validator only checks format or simple rules
from pydantic import BaseModel, validator

class User(BaseModel):
username: str

@validator('username')
def check_username_format(cls, v):
if ' ' in v:
raise ValueError('no spaces allowed')
return v

Root cause:

Not understanding that validators run on every model creation and expensive calls slow down the app.

Key Takeaways

Custom validators in FastAPI extend Pydantic's automatic data checks to enforce your specific rules.

They are methods inside your data models decorated with @validator or @root_validator to check single or multiple fields.

Validators must be synchronous; async validation belongs in FastAPI dependencies or route logic.

Validators run every time data is parsed, so keep them efficient and order them to catch common errors first.

Understanding custom validators helps you build safer, clearer, and more reliable APIs that handle data exactly as you want.