Complex Pydantic Models

So you've mastered the basics of Pydantic models — simple fields, types, and validation. But real-world APIs deal with messy, nested data: users with multiple addresses, orders containing line items, config files with optional sections. If you try to model that with flat models, your code quickly becomes a swamp of dictionaries and manual parsing. This lesson fixes that. You'll learn to define complex Pydantic models that mirror your actual data structures, so validation, serialization, and type safety just work — even for deeply nested data. By the end, you'll be confident describing intricate JSON payloads with minimal, expressive code.

The problem this lesson solves

Flat Pydantic models break down fast. Imagine an API that accepts a User object. A simple User with name and email works fine. But what about a user with multiple addresses? Each address has street, city, zip, and maybe country. Or an Order with a list of items, each with its own name, price, and quantity. Trying to squeeze that into a single flat model means:

• Repetitive validation logic — you'd write manual checks for every nested field.
• Fragile data handling — accessing nested fields becomes data['shipping']['address']['street'] — brittle and error-prone.
• Poor type hints — IDE autocomplete disappears, and you lose the safety net of static typing.
• Messy documentation — FastAPI's automatic OpenAPI docs become useless or misleading.

The pain hits worst when you're building real features: user profiles, checkout flows, payment APIs, or any domain (ecommerce, logistics, SaaS) with structured entities. You need a systematic way to define nested, optional, and validated data — and that's exactly what complex Pydantic models provide.

Core concept / mental model

Think of complex Pydantic models as blueprints within blueprints. A simple model is a one-room blueprint. A complex model is a full building blueprint: each room (a nested model) has its own layout, but they all assemble into one coherent structure.

• Model nesting: A Pydantic model can have a field whose type is another Pydantic model just like it can have str or int. That's the fundamental building block.
• List types: list[Address] means "a list of Address objects" — Pydantic validates each element automatically.
• Optional fields: Optional[Type] or type | None means the field can be missing or None — critical for partial data.
• Default values: You can provide defaults, either static (field1 = "default") or dynamic (field2: str = Field(default_factory=lambda: "generated")).
• Recursive models: A model can reference itself (e.g., a category with subcategories) — useful for trees.

Pro tip: The mental model that unlocks everything: Pydantic doesn't care if your field is a primitive or a whole model — validation works the same way. Once you internalize that, complex schemas feel natural.

How it works step by step

Let's build complexity gradually, from a single model to a realistic nested schema.

Step 1: Define the leaf models

Start with the smallest, most fundamental models — the ones with only primitive fields.

from pydantic import BaseModel, EmailStr

class Address(BaseModel):
    street: str
    city: str
    zip_code: str
    country: str = "US"  # default value

class UserBase(BaseModel):
    name: str
    email: EmailStr

Step 2: Nest them into a parent model

Now use those smaller models as field types inside a larger one.

from typing import Optional

class User(UserBase):
    addresses: list[Address] = []  # empty list default
    age: Optional[int] = None      # can be missing or null
    tags: list[str] = []           # simple list type

Step 3: Add deeper nesting and lists of models

Combine nesting with lists to model collections of related objects.

class OrderItem(BaseModel):
    product_id: int
    name: str
    price: float
    quantity: int = 1

class Order(BaseModel):
    order_id: str
    user: User
    items: list[OrderItem]
    total: float
    created_at: Optional[str] = None

Step 4: Use Field for extra validation and metadata

Field() lets you set constraints, defaults, and descriptions directly on model fields.

from pydantic import Field

class Product(BaseModel):
    name: str = Field(..., min_length=3, description="Product name")
    price: float = Field(..., gt=0, description="Price in USD")
    stock: int = Field(default=0, ge=0)

Pro tip: Use ... (ellipsis) as the first argument in Field() to mark a field as required — it's clearer than a raw type annotation.

Hands-on walkthrough

Now let's put it all together in a realistic example — an e-commerce order schema. Below is a complete, runnable script that defines complex models, validates both good and bad data, and shows exactly what happens.

from pydantic import BaseModel, EmailStr, Field, ValidationError
from typing import Optional

class Address(BaseModel):
    street: str
    city: str
    zip_code: str
    country: str = "US"

class User(BaseModel):
    name: str
    email: EmailStr
    addresses: list[Address] = []

class OrderItem(BaseModel):
    product_id: int
    name: str
    price: float = Field(..., gt=0)
    quantity: int = Field(default=1, ge=1)

class Order(BaseModel):
    order_id: str
    user: User
    items: list[OrderItem]
    total: float = Field(..., gt=0)

# Valid payload
valid_data = {
    "order_id": "ORD-001",
    "user": {
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "addresses": [
            {"street": "1 Analytical Ave", "city": "London", "zip_code": "SW1A"}
        ]
    },
    "items": [
        {"product_id": 1, "name": "Laptop", "price": 999.99, "quantity": 1},
        {"product_id": 2, "name": "Mouse", "price": 19.99}
    ],
    "total": 1019.98
}

order = Order(**valid_data)
print(order)
print("User addresses:", order.user.addresses[0].city)

# Invalid payload — price is zero, which violates gt=0
invalid_data = {
    "order_id": "ORD-002",
    "user": {"name": "Grace Hopper", "email": "grace@example.com"},
    "items": [{"product_id": 3, "name": "Keypad", "price": 0}],
    "total": 0
}

try:
    Order(**invalid_data)
except ValidationError as e:
    print("Errors:")
    for err in e.errors():
        print(f"- {err['loc']}: {err['msg']}")

Expected output:

The script will print the validated Order model (with the default country="US" and quantity=1 applied), the nested address city, and then a list of validation errors for the invalid data — for example ('items', 0, 'price') and ('total',).

That's the power: you get automatic coercion, defaults, and comprehensive error messages for deeply nested structures — all in a few lines of declarative code.

Using complex models in FastAPI endpoints

Here's how you'd use such a model in a FastAPI route — FastAPI will use the model for request validation, response serialization, and OpenAPI docs.

from fastapi import FastAPI

app = FastAPI()

@app.post("/orders/")
async def create_order(order: Order) -> Order:
    # In a real app, you'd save to a database
    return order

That endpoint automatically rejects invalid payloads with 422 Unprocessable Entity, and the docs show a beautifully structured JSON schema.

Compare options / when to choose what

Recommendation: As soon as your payload has more than one level of nesting or any kind of list of objects, go with nested models and Field. The cost is tiny, the payoff is massive.

Troubleshooting & edge cases

ValidationError: field required

You'll see this when a required field is missing. Double-check that your input JSON contains every required field — remember that fields with a default (including = []) are optional.

Pydantic doesn't coerce strings to floats

By default, Pydantic is strict about some type coercions. For example, float fields might not accept a string "9.99" — you may need ConfigDict(coerce_numbers_to_str=True) or to handle the conversion yourself. (Actually, Pydantic v2 allows coercion from numeric strings to floats by default, but not from arbitrary strings — be explicit if you need it.)

Recursive models without forward references

If you have a self-referencing model (e.g., a Category with subcategories: list[Category]), you need to use forward references or model_rebuild(). Example:

class Category(BaseModel):
    name: str
    subcategories: list["Category"] = []

Category.model_rebuild()  # resolve the forward reference

Default mutable lists and Field(default_factory=

Do not use a mutable default like addresses: list[Address] = [] in a regular Python class — but Pydantic handles it safely by creating a new list per instance. However, for clarity and to avoid confusion, prefer Field(default_factory=list):

class User(BaseModel):
    addresses: list[Address] = Field(default_factory=list)

Deeply nested validation errors

The loc tuple in ValidationError gives you the full path: ('items', 2, 'price') means the third item's price. Use that to give users precise feedback.

Model not validating because you used a dict

Always declare the field type as another BaseModel class, not dict. If you use dict, Pydantic won't validate the content — you lose all type safety.

What you learned & what's next

You've learned how to define defining more complex pydantic models — from nesting models inside models, to using lists and optional fields, to adding Field constraints. You applied this in a hands-on e-commerce order example, compared different modeling approaches, and know how to troubleshoot validation errors. You're now equipped to design API schemas that mirror your domain.

Next in the FastAPI track, you'll tackle how to work with query parameters and request bodies — combining Pydantic models with FastAPI's parameter handling for full-featured endpoints. That's where your complex models become truly powerful.

Key takeaway: Complex Pydantic models are not a luxury — they're the foundation of clean, maintainable APIs. Master them now, and the rest of FastAPI becomes much easier.