FastAPI Validation

Master FastAPI validation with Pydantic for building type-safe APIs with comprehensive request and response validation.

Pydantic BaseModel Fundamentals

Core Pydantic patterns with Pydantic v2.

from pydantic import BaseModel, Field, ConfigDict from typing import Optional from datetime import datetime

Basic model

class User(BaseModel): id: int name: str email: str created_at: datetime

With defaults and optional fields

class UserCreate(BaseModel): name: str email: str age: Optional[int] = None is_active: bool = True

With Field constraints

class Product(BaseModel): name: str = Field(..., min_length=1, max_length=100) price: float = Field(..., gt=0, le=1000000) quantity: int = Field(default=0, ge=0) description: Optional[str] = Field(None, max_length=500)

model_config = ConfigDict(
    str_strip_whitespace=True,
    validate_assignment=True,
    json_schema_extra={
        'example': {
            'name': 'Widget',
            'price': 29.99,
            'quantity': 100,
            'description': 'A useful widget'
        }
    }
)

Request Body Validation

Validating complex request bodies.

from fastapi import FastAPI, HTTPException from pydantic import BaseModel, EmailStr, Field from typing import List

app = FastAPI()

Simple request validation

class CreateUserRequest(BaseModel): username: str = Field(..., min_length=3, max_length=50) email: EmailStr password: str = Field(..., min_length=8) age: int = Field(..., ge=13, le=120)

@app.post('/users') async def create_user(user: CreateUserRequest): # user is automatically validated return {'username': user.username, 'email': user.email}

Nested models

class Address(BaseModel): street: str city: str state: str = Field(..., min_length=2, max_length=2) zip_code: str = Field(..., pattern=r'^\d{5}(-\d{4})?$')

class UserProfile(BaseModel): name: str email: EmailStr address: Address phone: Optional[str] = Field(None, pattern=r'^+?1?\d{9,15}$')

@app.post('/profiles') async def create_profile(profile: UserProfile): return profile

List validation

class BulkCreateRequest(BaseModel): users: List[CreateUserRequest] = Field(..., min_length=1, max_length=100)

@app.post('/users/bulk') async def bulk_create_users(request: BulkCreateRequest): return {'count': len(request.users)}

Complex nested structures

class Tag(BaseModel): name: str color: str = Field(..., pattern=r'^#[0-9A-Fa-f]{6}$')

class Post(BaseModel): title: str = Field(..., min_length=1, max_length=200) content: str tags: List[Tag] = [] author: UserProfile published: bool = False

@app.post('/posts') async def create_post(post: Post): return post

Query Parameter Validation

Validating query parameters with Field constraints.

from fastapi import FastAPI, Query from typing import Optional, List from enum import Enum

app = FastAPI()

Simple query params

@app.get('/users') async def get_users( skip: int = Query(0, ge=0), limit: int = Query(10, ge=1, le=100), search: Optional[str] = Query(None, min_length=3, max_length=50) ): return {'skip': skip, 'limit': limit, 'search': search}

Enum validation

class SortOrder(str, Enum): asc = 'asc' desc = 'desc'

class SortField(str, Enum): name = 'name' created_at = 'created_at' updated_at = 'updated_at'

@app.get('/items') async def get_items( sort_by: SortField = Query(SortField.created_at), order: SortOrder = Query(SortOrder.desc) ): return {'sort_by': sort_by, 'order': order}

Multiple values

@app.get('/filter') async def filter_items( tags: List[str] = Query([]), categories: List[int] = Query([], max_length=10) ): return {'tags': tags, 'categories': categories}

Regex pattern

@app.get('/search') async def search( q: str = Query(..., min_length=1, max_length=100, pattern=r'^[a-zA-Z0-9\s]+$') ): return {'query': q}

Path Parameter Validation

Validating URL path parameters.

from fastapi import FastAPI, Path from typing import Annotated

app = FastAPI()

@app.get('/users/{user_id}') async def get_user( user_id: int = Path(..., gt=0, description='The user ID') ): return {'user_id': user_id}

@app.get('/items/{item_id}/reviews/{review_id}') async def get_review( item_id: Annotated[int, Path(gt=0)], review_id: Annotated[int, Path(gt=0)] ): return {'item_id': item_id, 'review_id': review_id}

String path validation

@app.get('/categories/{category_name}') async def get_category( category_name: str = Path(..., min_length=1, max_length=50, pattern=r'^[a-z-]+$') ): return {'category': category_name}

Custom Validators

Field validators and model validators with Pydantic v2.

from pydantic import BaseModel, field_validator, model_validator from typing import Any import re

class UserRegistration(BaseModel): username: str email: str password: str password_confirm: str

@field_validator('username')
@classmethod
def username_alphanumeric(cls, v: str) -> str:
    if not re.match(r'^[a-zA-Z0-9_]+$', v):
        raise ValueError('Username must be alphanumeric')
    if len(v) < 3:
        raise ValueError('Username must be at least 3 characters')
    return v.lower()

@field_validator('email')
@classmethod
def validate_email_domain(cls, v: str) -> str:
    if not v.endswith(('@example.com', '@example.org')):
        raise ValueError('Email must be from example.com or example.org')
    return v.lower()

@field_validator('password')
@classmethod
def password_strength(cls, v: str) -> str:
    if len(v) < 8:
        raise ValueError('Password must be at least 8 characters')
    if not re.search(r'[A-Z]', v):
        raise ValueError('Password must contain uppercase letter')
    if not re.search(r'[a-z]', v):
        raise ValueError('Password must contain lowercase letter')
    if not re.search(r'[0-9]', v):
        raise ValueError('Password must contain digit')
    return v

@model_validator(mode='after')
def check_passwords_match(self) -> 'UserRegistration':
    if self.password != self.password_confirm:
        raise ValueError('Passwords do not match')
    return self

Validator with dependencies

class DateRange(BaseModel): start_date: datetime end_date: datetime

@model_validator(mode='after')
def check_dates(self) -> 'DateRange':
    if self.start_date >= self.end_date:
        raise ValueError('start_date must be before end_date')
    return self

Computed fields

from pydantic import computed_field

class Product(BaseModel): name: str price: float tax_rate: float = 0.1

@computed_field
@property
def price_with_tax(self) -> float:
    return round(self.price * (1 + self.tax_rate), 2)

Before validator

class UserInput(BaseModel): name: str email: str

@field_validator('name', 'email', mode='before')
@classmethod
def strip_whitespace(cls, v: Any) -> Any:
    if isinstance(v, str):
        return v.strip()
    return v

Field Types

Specialized field types for validation.

from pydantic import ( BaseModel, EmailStr, HttpUrl, SecretStr, conint, constr, confloat, conlist, UUID4, IPvAnyAddress, FilePath, DirectoryPath, Json ) from typing import List from datetime import date, time

class AdvancedUser(BaseModel): # String constraints username: constr(min_length=3, max_length=50, pattern=r'^[a-zA-Z0-9_]+$') bio: constr(max_length=500) | None = None

# Email and URL
email: EmailStr
website: HttpUrl | None = None

# Numeric constraints
age: conint(ge=13, le=120)
rating: confloat(ge=0.0, le=5.0)

# Secret fields (won't be logged)
password: SecretStr
api_key: SecretStr

# UUID
user_id: UUID4

# Network
ip_address: IPvAnyAddress | None = None

# Date and time
birth_date: date
preferred_time: time | None = None

# Lists with constraints
tags: conlist(str, min_length=1, max_length=10)

# JSON field
metadata: Json | None = None

File path validation

class FileUploadConfig(BaseModel): upload_dir: DirectoryPath allowed_file: FilePath | None = None

Nested Models and Composition

Building complex models from simpler ones.

from pydantic import BaseModel from typing import List, Optional

Composition

class Coordinates(BaseModel): latitude: float = Field(..., ge=-90, le=90) longitude: float = Field(..., ge=-180, le=180)

class Location(BaseModel): name: str coordinates: Coordinates address: Optional[str] = None

class Event(BaseModel): title: str description: str location: Location attendees: List[str] = []

Inheritance

class BaseUser(BaseModel): username: str email: EmailStr

class AdminUser(BaseUser): permissions: List[str] is_superuser: bool = False

class RegularUser(BaseUser): subscription_tier: str = 'free'

Model reuse

class TimestampMixin(BaseModel): created_at: datetime updated_at: datetime

class Post(TimestampMixin): title: str content: str author_id: int

class Comment(TimestampMixin): content: str post_id: int author_id: int

Model Configuration

ConfigDict options for model behavior.

from pydantic import BaseModel, ConfigDict, Field

Strict mode

class StrictModel(BaseModel): model_config = ConfigDict(strict=True)

id: int  # Won't coerce from string
name: str

ORM mode (for database models)

class UserORM(BaseModel): model_config = ConfigDict(from_attributes=True)

id: int
name: str
email: str

Usage with SQLAlchemy

from sqlalchemy import Column, Integer, String from sqlalchemy.orm import declarative_base

Base = declarative_base()

class UserModel(Base): tablename = 'users' id = Column(Integer, primary_key=True) name = Column(String) email = Column(String)

@app.get('/users/{user_id}', response_model=UserORM) async def get_user(user_id: int, db = Depends(get_db)): user = db.query(UserModel).filter(UserModel.id == user_id).first() return user # Automatically converted to UserORM

Populate by name

class FlexibleModel(BaseModel): model_config = ConfigDict(populate_by_name=True)

user_id: int = Field(alias='userId')
user_name: str = Field(alias='userName')

Allow extra fields

class ExtraFieldsModel(BaseModel): model_config = ConfigDict(extra='allow')

name: str
# Any extra fields will be stored

Forbid extra fields

class StrictFieldsModel(BaseModel): model_config = ConfigDict(extra='forbid')

name: str
# Extra fields will raise validation error

Response Models

Validating and shaping API responses.

from fastapi import FastAPI from pydantic import BaseModel from typing import List

app = FastAPI()

class UserCreate(BaseModel): username: str email: EmailStr password: str

class UserResponse(BaseModel): id: int username: str email: str # Note: password excluded

model_config = ConfigDict(from_attributes=True)

@app.post('/users', response_model=UserResponse) async def create_user(user: UserCreate): # Create user in database db_user = create_user_in_db(user) return db_user # Password automatically excluded

Response with exclude

class UserDetail(BaseModel): id: int username: str email: str password_hash: str secret_key: str

@app.get('/users/{user_id}', response_model=UserDetail, response_model_exclude={'password_hash', 'secret_key'}) async def get_user_detail(user_id: int): return get_user_from_db(user_id)

Response with include

@app.get('/users/{user_id}/public', response_model=UserDetail, response_model_include={'id', 'username'}) async def get_user_public(user_id: int): return get_user_from_db(user_id)

List response

@app.get('/users', response_model=List[UserResponse]) async def list_users(): return get_all_users()

Optional response

from typing import Optional

@app.get('/users/{user_id}/optional', response_model=Optional[UserResponse]) async def get_user_optional(user_id: int): user = get_user_from_db(user_id) return user # Can be None

Union response

from typing import Union

class SuccessResponse(BaseModel): status: str = 'success' data: dict

class ErrorResponse(BaseModel): status: str = 'error' message: str

@app.get('/data', response_model=Union[SuccessResponse, ErrorResponse]) async def get_data(): try: data = fetch_data() return SuccessResponse(data=data) except Exception as e: return ErrorResponse(message=str(e))

Error Handling

Custom error messages and validation error handling.

from fastapi import FastAPI, HTTPException, Request, status from fastapi.exceptions import RequestValidationError from fastapi.responses import JSONResponse from pydantic import BaseModel, ValidationError

app = FastAPI()

Custom validation error handler

@app.exception_handler(RequestValidationError) async def validation_exception_handler(request: Request, exc: RequestValidationError): errors = [] for error in exc.errors(): errors.append({ 'field': '.'.join(str(loc) for loc in error['loc'][1:]), 'message': error['msg'], 'type': error['type'] })

return JSONResponse(
    status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
    content={'errors': errors}
)

Custom field error messages

class User(BaseModel): username: str = Field(..., min_length=3, description='Username must be at least 3 characters') age: int = Field(..., ge=18, description='Must be 18 or older')

Programmatic validation

async def validate_user_data(data: dict): try: user = User(**data) return user except ValidationError as e: raise HTTPException( status_code=422, detail=e.errors() )

File Upload Validation

Validating file uploads.

from fastapi import FastAPI, File, UploadFile, HTTPException from typing import List

app = FastAPI()

@app.post('/upload') async def upload_file(file: UploadFile = File(...)): # Validate file type allowed_types = ['image/jpeg', 'image/png', 'image/gif'] if file.content_type not in allowed_types: raise HTTPException( status_code=400, detail=f'File type {file.content_type} not allowed' )

# Validate file size
contents = await file.read()
max_size = 5 * 1024 * 1024  # 5MB
if len(contents) > max_size:
    raise HTTPException(
        status_code=400,
        detail='File too large (max 5MB)'
    )

# Validate filename
if not file.filename.endswith(('.jpg', '.jpeg', '.png', '.gif')):
    raise HTTPException(
        status_code=400,
        detail='Invalid file extension'
    )

return {'filename': file.filename, 'size': len(contents)}

Multiple files

@app.post('/upload-multiple') async def upload_multiple_files(files: List[UploadFile] = File(...)): if len(files) > 10: raise HTTPException( status_code=400, detail='Maximum 10 files allowed' )

results = []
for file in files:
    contents = await file.read()
    results.append({
        'filename': file.filename,
        'size': len(contents)
    })

return results

Form Data Validation

Validating form data submissions.

from fastapi import FastAPI, Form from pydantic import BaseModel, ValidationError

app = FastAPI()

Simple form

@app.post('/login') async def login( username: str = Form(..., min_length=3), password: str = Form(..., min_length=8) ): return {'username': username}

Form with validation model

class LoginForm(BaseModel): username: str = Field(..., min_length=3) password: str = Field(..., min_length=8)

@app.post('/login-validated') async def login_validated( username: str = Form(...), password: str = Form(...) ): try: form = LoginForm(username=username, password=password) return {'username': form.username} except ValidationError as e: raise HTTPException(status_code=422, detail=e.errors())

Form with file

@app.post('/profile') async def update_profile( name: str = Form(..., min_length=1), bio: str = Form(None, max_length=500), avatar: UploadFile = File(None) ): result = {'name': name, 'bio': bio} if avatar: result['avatar_filename'] = avatar.filename return result

Advanced Patterns

Discriminated unions and recursive models.

from pydantic import BaseModel, Field, Discriminator from typing import Literal, Union, List

Discriminated unions

class Cat(BaseModel): pet_type: Literal['cat'] meows: int

class Dog(BaseModel): pet_type: Literal['dog'] barks: float

Pet = Union[Cat, Dog]

class PetOwner(BaseModel): name: str pet: Pet

@app.post('/pets') async def create_pet(owner: PetOwner): # Automatically discriminates based on pet_type return owner

Recursive models

class TreeNode(BaseModel): value: int children: List['TreeNode'] = []

TreeNode.model_rebuild() # Required for recursive models

@app.post('/tree') async def create_tree(tree: TreeNode): return tree

Generic models

from typing import TypeVar, Generic

T = TypeVar('T')

class Response(BaseModel, Generic[T]): data: T message: str success: bool = True

class UserData(BaseModel): id: int name: str

@app.get('/user/{user_id}', response_model=Response[UserData]) async def get_user(user_id: int): user = UserData(id=user_id, name='John Doe') return Response(data=user, message='User retrieved')

When to Use This Skill

Use fastapi-validation when:

• Building APIs that require strict input validation

• Ensuring type safety across request and response models

• Implementing complex validation rules and business logic

• Converting between database models and API schemas

• Documenting API schemas with OpenAPI

• Preventing invalid data from entering your system

• Building forms with server-side validation

• Handling file uploads with validation

• Creating reusable validation patterns

FastAPI Validation Best Practices

• Use specific types - Use EmailStr, HttpUrl, UUID instead of plain str for better validation

• Separate request and response - Create different models for input and output

• Leverage computed fields - Use computed fields for derived values instead of manual calculation

• Validate early - Validate at API boundary before business logic

• Custom validators - Create reusable validators for common patterns

• Meaningful error messages - Provide clear, actionable error messages

• Use aliases - Handle different naming conventions (camelCase, snake_case) with aliases

• Exclude sensitive data - Always exclude passwords and secrets from responses

• ORM mode - Enable from_attributes for database model conversion

• Document examples - Use json_schema_extra to provide example data

FastAPI Validation Common Pitfalls

• Missing response_model - Not using response_model exposes all fields including secrets

• Incorrect Field usage - Using Field without ... for required fields makes them optional

• Validator order - Validators run in definition order, dependencies matter

• Coercion confusion - Pydantic coerces types by default, use strict mode when needed

• Recursive model rebuild - Forgetting model_rebuild() on recursive models causes errors

• Form data limitations - Form data doesn't support nested models directly

• List validation - Not setting max_length on lists can allow resource exhaustion

• Regex complexity - Complex regex patterns can cause performance issues

• Timezone handling - datetime fields need explicit timezone handling

• Union validation - Union types validate in order, put more specific types first

Resources

• Pydantic V2 Documentation

• FastAPI Request Body

• FastAPI Response Model

• Pydantic Field Types

• Pydantic Validators

• FastAPI Form Data

• FastAPI File Uploads

• Pydantic Configuration