---

name: fastapi-validation description: Use when FastAPI validation with Pydantic models. Use when building type-safe APIs with robust request/response validation. allowed-tools:

• Bash
• Read

---

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

1. Use specific types - Use EmailStr, HttpUrl, UUID instead of plain str for better validation
2. Separate request and response - Create different models for input and output
3. Leverage computed fields - Use computed fields for derived values instead of manual calculation
4. Validate early - Validate at API boundary before business logic
5. Custom validators - Create reusable validators for common patterns
6. Meaningful error messages - Provide clear, actionable error messages
7. Use aliases - Handle different naming conventions (camelCase, snake_case) with aliases
8. Exclude sensitive data - Always exclude passwords and secrets from responses
9. ORM mode - Enable from_attributes for database model conversion
10. Document examples - Use json_schema_extra to provide example data

FastAPI Validation Common Pitfalls

1. Missing response_model - Not using response_model exposes all fields including secrets
2. Incorrect Field usage - Using Field without ... for required fields makes them optional
3. Validator order - Validators run in definition order, dependencies matter
4. Coercion confusion - Pydantic coerces types by default, use strict mode when needed
5. Recursive model rebuild - Forgetting model_rebuild() on recursive models causes errors
6. Form data limitations - Form data doesn't support nested models directly
7. List validation - Not setting max_length on lists can allow resource exhaustion
8. Regex complexity - Complex regex patterns can cause performance issues
9. Timezone handling - datetime fields need explicit timezone handling
10. 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