Master Pydantic: Data Validation for Python

A BaseModel is a class that automatically validates data when you create an instance from it. Every field is defined with a Python type annotation, and Pydantic enforces that type at instantiation time.

python
from pydantic import BaseModel

class User(BaseModel):
    name: str
    email: str
    age: int

user = User(name="Alice", email="alice@example.com", age=30)
print(user.name)  # Alice
print(user.age)   # 30

---

When you pass invalid data — a string for an integer field, for example — Pydantic raises a ValidationError instead of silently accepting bad data. This is the core insight: validation happens automatically, you never need to write isinstance() checks.

python
try:
    bad_user = User(name="Bob", email="bob@example.com", age="not a number")
except ValidationError as e:
    print(e.errors())  # List of validation failures

Pydantic's type annotations are not just hints — they are enforcement rules. When you define a field with type str, int, or bool, Pydantic checks that the value matches the type and rejects it if it doesn't.

python
from pydantic import BaseModel, EmailStr

class Account(BaseModel):
    username: str
    age: int
    is_active: bool

account = Account(username="alice", age=25, is_active=True)

---

Pydantic goes beyond simple type checking. It coerces values intelligently: a string "42" becomes the integer 42, and "true" becomes the boolean True. However, you can set strict=True on a field to reject coercion and require exact types. Types like list, dict, and datetime objects are all validated automatically based on their shape and structure.

By default, every field in a Pydantic model is required — you must provide a value when instantiating the model. To make a field optional, use Optional[type] or provide a default value using Field() or assignment syntax.

python
from pydantic import BaseModel, Field
from typing import Optional

class Config(BaseModel):
    database_url: str
    max_connections: int = 10
    debug_mode: Optional[bool] = None

config = Config(database_url="postgres://localhost")
print(config.max_connections)  # 10
print(config.debug_mode)        # None

---

You can also use Field() to set a default and add metadata like a description or constraints. Field() gives you fine-grained control: set the default, add a validation constraint, provide a description for API docs, and control how the field is serialized. Optional fields with None as the default are a common pattern for nullable data.

The Field() function lets you attach metadata to each field: a description, constraints (min/max), aliases for input, and serialization rules. This metadata is used by Pydantic's JSON schema generation and makes API documentation automatic.

python
from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(..., description="Product name")
    price: float = Field(gt=0, description="Price in USD (must be positive)")
    quantity: int = Field(ge=0, description="Stock quantity (non-negative)")

product = Product(name="Laptop", price=999.99, quantity=10)

---

When validation fails, Pydantic includes a descriptive error message that mentions the constraint. You can also customize error messages using the errors.json_schema_extra option or by writing custom validators. Field constraints like gt (greater than), ge (greater than or equal), le (less than or equal), and max_length are enforced automatically. Aliases let you accept different field names in input JSON while mapping them to your Python names internally.

A field validator is a function decorated with @field_validator that runs whenever a field is assigned. It receives the field value and the validation info context, and can either return the value (optionally modified) or raise a validation error.

python
from pydantic import BaseModel, field_validator

class Account(BaseModel):
    username: str
    password: str

    @field_validator('password')
    @classmethod
    def validate_password(cls, v):
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        return v

account = Account(username='alice', password='securepassword')

---

Fieldvalidators run in the order they are defined and have access to the validation info context (includes the raw input data and the validation mode). You can apply the same validator to multiple fields using a tuple of field names, or use mode='before' to validate the raw input before type coercion. Returning a modified value lets you normalize input — for example, converting a URL to lowercase or stripping whitespace.

A model validator is a function decorated with @model_validator that runs after all fields are assigned. It receives the entire model as a dictionary or instance and can enforce rules that span multiple fields.

python
from pydantic import BaseModel, model_validator

class Address(BaseModel):
    street: str
    city: str
    zip_code: str
    country: str

    @model_validator(mode='after')
    def validate_address(self):
        if self.country == 'US' and len(self.zip_code) != 5:
            raise ValueError('US zip codes must be 5 digits')
        return self

addr = Address(street='123 Main', city='NYC', zip_code='10001', country='US')

---

Model validators are essential for validating cross-field dependencies. Use mode='after' to validate the fully typed model, or mode='before' to validate raw input before type coercion. Unlike field validators, model validators see all fields at once and can make decisions based on combinations of values. This pattern is ideal for rules like "if country is US, zip code must follow US format."

Instead of raising a generic ValueError, you can raise a PydanticCustomError to provide structured error information that Pydantic includes in the ValidationError. This gives you control over error codes, context, and the exact message users see.

python
from pydantic import BaseModel, field_validator, PydanticCustomError

class SignUp(BaseModel):
    email: str
    age: int

    @field_validator('age')
    @classmethod
    def validate_age(cls, v):
        if v < 13:
            raise PydanticCustomError(
                'age_too_young',
                'Users must be at least 13 years old',
            )
        return v

signup = SignUp(email='user@example.com', age=10)

---

PydanticCustomError takes an error code (a slug like 'age_too_young'), a message template, and optional context dict. The error code is useful for i18n (internationalization) and for the client to show localized messages. API responses can include the error code and context so frontend applications can handle errors programmatically instead of relying only on strings.

Field validators with mode='before' and model validators with mode='before' let you transform data before type coercion happens. This is useful for normalizing input — for example, converting a date string in multiple formats to a standard format, lowercasing email addresses, or stripping whitespace.

python
from pydantic import BaseModel, field_validator
from datetime import date

class Event(BaseModel):
    name: str
    date_str: str

    @field_validator('date_str', mode='before')
    @classmethod
    def parse_date(cls, v):
        if isinstance(v, str):
            # Try parsing ISO format first, then other formats
            try:
                return date.fromisoformat(v)
            except:
                return date(2025, 1, 1)
        return v

event = Event(name='Launch', date_str='2025-03-04')

---

Transformations during validation are more efficient than post-instantiation cleanup and keep your model in a consistent state from the moment it exists. Use mode='before' to normalize raw input before Pydantic's type system touches it, and mode='after' to refine already-typed fields. The transformation pattern is essential for handling user input from APIs, forms, or files where formats vary.

A Pydantic model can include other Pydantic models as fields, creating a hierarchy. When you nest models, Pydantic validates the nested data according to the inner model's rules before constructing the outer model.

python
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zip_code: str

class Customer(BaseModel):
    name: str
    email: str
    address: Address

customer = Customer(
    name="Alice",
    email="alice@example.com",
    address={"street": "123 Main", "city": "NYC", "zip_code": "10001"}
)

---

Pydantic automatically validates the nested data: if the address data is missing a field or has an invalid type, a ValidationError is raised before the Customer model is created. You can nest as deeply as you need, and even create circular relationships using forward references. Lists of models are also supported: items: list[Item] means Pydantic validates each Item in the list.

ConfigDict lets you control Pydantic's behavior for a model: whether to validate on assignment, whether to freeze the model (make it immutable), JSON schema generation settings, and more.

python
from pydantic import BaseModel, ConfigDict

class User(BaseModel):
    model_config = ConfigDict(
        frozen=True,
        validate_assignment=True,
        json_schema_extra={"examples": [{"name": "Alice", "age": 30}]}
    )
    name: str
    age: int

user = User(name="Alice", age=30)
user.age = 31  # Raises ValidationError because frozen=True

---

Common ConfigDict settings: frozen=True makes the model immutable; validate_assignment=True validates changes to fields after instantiation; str_strip_whitespace=True removes leading/trailing spaces from strings; json_schema_extra adds custom metadata to the generated JSON schema. Use different models with different configs for different use cases — a database model might allow assignment, while an API response model might be frozen.

Every Pydantic model can export itself as a JSON schema, a standardized format that describes the structure of the model. Use model_json_schema() to generate the schema, which includes field types, descriptions, constraints, and examples.

python
from pydantic import BaseModel, Field
import json

class Product(BaseModel):
    name: str = Field(..., description="Product name")
    price: float = Field(gt=0, description="Price in USD")
    in_stock: bool = Field(default=True)

schema = Product.model_json_schema()
print(json.dumps(schema, indent=2))

---

JSON schema is the foundation for API documentation tools like Swagger/OpenAPI. FastAPI automatically generates interactive API docs from your Pydantic models using JSON schema. The schema includes all your Field descriptions, constraints, default values, and examples — everything needed for API users to understand the data contract. You can customize the schema using ConfigDict's json_schema_extra setting.

Serialization is converting a model instance to JSON or Python dict. Use model_dump() and model_dump_json() to serialize. You can include/exclude fields, convert enum values, and apply custom serializers.

python
from pydantic import BaseModel, field_serializer

class User(BaseModel):
    name: str
    email: str
    password: str

    @field_serializer('password')
    def serialize_password(self, value):
        return '***'

user = User(name="Alice", email="alice@example.com", password="secret")
print(user.model_dump())  # {"name": "Alice", "email": "alice@example.com", "password": "***"}

---

Use model_dump(include={...}, exclude={...}) to control which fields appear in the output. The exclude_none=True flag removes None values. by_alias=True uses field aliases in the output. Custom field serializers with @field_serializer let you transform values during serialization — mask sensitive data, format dates, or compute derived fields. Different API responses often need different serializations of the same model.

FastAPI is built on Pydantic. When you define a route with a Pydantic model as a parameter, FastAPI automatically validates the incoming JSON and deserializes it into the model. If validation fails, FastAPI returns a 422 Unprocessable Entity response with detailed error information.

python
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class User(BaseModel):
    name: str
    email: str = Field(..., pattern=r'.*@.*')
    age: int = Field(ge=18)

@app.post('/users')
def create_user(user: User):
    return {"message": f"User {user.name} created", "user": user}

---

FastAPI uses Pydantic models for both request bodies and response bodies. When you specify a model as a route parameter, FastAPI automatically generates OpenAPI/Swagger documentation from the model's JSON schema. Validation errors are caught before your route handler runs, keeping your code clean. You can also use Pydantic models for query parameters, path parameters, and headers.

Pydantic models can represent database rows. You often create separate models for database operations (with database IDs) and API responses (without internal fields). This separation keeps your API contract decoupled from your database schema.

python
from pydantic import BaseModel
from datetime import datetime

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

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

class UserResponse(BaseModel):
    id: int
    name: str
    email: str

---

Create three models: UserCreate (accepts user input without IDs), UserDB (represents database rows with IDs and timestamps), and UserResponse (what the API returns). Validate user input against UserCreate before inserting into the database, then convert the database row to UserResponse for the API response. This pattern keeps validation logic separate from data access.

Third-party APIs don't always return exactly what you expect. Fields may be missing, have unexpected types, or contain extra data. Use Pydantic models with ConfigDict(extra='ignore') to handle missing fields gracefully and ignore unexpected ones.

python
from pydantic import BaseModel, ConfigDict, field_validator
import requests

class WeatherAPI(BaseModel):
    model_config = ConfigDict(extra='ignore')
    temp: float
    humidity: int
    location: str

    @field_validator('humidity', mode='before')
    @classmethod
    def coerce_humidity(cls, v):
        # API might return humidity as a string "85%"
        if isinstance(v, str):
            return int(v.rstrip('%'))
        return v

response = requests.get('https://api.weather.example.com/current')
weather = WeatherAPI(**response.json())

---

Use ConfigDict(extra='allow') to accept extra fields, extra='forbid' to reject them, or extra='ignore' (default) to silently drop them. Combine with field validators to normalize API responses: parse date strings, extract nested values, and handle alternative field names using aliases.

A production validation pipeline combines all Pydantic techniques: parsing raw input, validating with models, logging failures, retrying on error, and storing cleaned data. Structure your pipeline to be resilient and observable.

python
from pydantic import BaseModel, ValidationError
from typing import Optional

class DataRecord(BaseModel):
    id: str
    value: int
    timestamp: str

def ingest_data(raw_records: list[dict]) -> dict:
    valid = []
    invalid = []
    
    for record in raw_records:
        try:
            validated = DataRecord(**record)
            valid.append(validated)
        except ValidationError as e:
            invalid.append({"record": record, "errors": e.errors()})
            # Log the error for monitoring
    
    return {"valid": valid, "invalid": invalid, "success_rate": len(valid) / len(raw_records)}

---

Production pipelines catch ValidationError, log the offending data with detailed error info, and track metrics like success rate. Store both valid records and failures separately for analysis. Use Pydantic's batch validation capabilities, validate upstream (at API boundaries), and downstream (before database insert) to catch errors early.