Nested Pydantic Models for Complex Data Structures

Real-world data is rarely flat. An order contains line items. A user has a billing address. An API response wraps a list of results in a metadata envelope. Pydantic handles all of this naturally — you use one model as the type annotation for a field inside another, and validation cascades through the entire structure automatically.

Using a model as a field type

To nest one model inside another, simply use the inner model’s class as the type annotation for a field:

from pydantic import BaseModel

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

class User(BaseModel):
    id:      int
    name:    str
    email:   str
    address: Address   # Address is a nested model

user = User(
    id=1,
    name="Alice Smith",
    email="[email protected]",
    address=Address(
        street="123 Main St",
        city="Amsterdam",
        country="Netherlands",
    ),
)

print(user.address.city)   # Amsterdam

You access nested fields with normal attribute chaining. Your IDE follows the types all the way down and provides autocompletion at every level.

Parsing nested data from a dictionary

The real power of nested models shows when you receive a nested dictionary — for example, from a JSON API response. You don’t need to construct inner models manually; Pydantic builds the entire object graph for you:

from pydantic import BaseModel

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

class User(BaseModel):
    id:      int
    name:    str
    email:   str
    address: Address

# Simulating a JSON API response parsed into a dict
api_data = {
    "id": 1,
    "name": "Alice Smith",
    "email": "[email protected]",
    "address": {
        "street": "123 Main St",
        "city": "Amsterdam",
        "country": "Netherlands",
    },
}

user = User.model_validate(api_data)

print(user.name)            # Alice Smith
print(user.address.city)    # Amsterdam
print(type(user.address))   # <class '__main__.Address'>

Pydantic sees that address should be an Address model, finds a dictionary at that key, and validates it automatically. If the nested dictionary is missing a required field or has a wrong type, you get a precise error pointing to the exact path that failed.

Lists of models

Use list[YourModel] to represent a collection of nested objects — a common pattern in API responses:

from pydantic import BaseModel

class OrderItem(BaseModel):
    product_id: str
    name:       str
    quantity:   int
    unit_price: float

class Order(BaseModel):
    order_id:       str
    customer_email: str
    items:          list[OrderItem]

order_data = {
    "order_id": "ORD-001",
    "customer_email": "[email protected]",
    "items": [
        {"product_id": "SKU-A1", "name": "Mechanical Keyboard", "quantity": 1, "unit_price": 89.99},
        {"product_id": "SKU-B7", "name": "USB-C Hub",           "quantity": 2, "unit_price": 29.99},
    ],
}

order = Order.model_validate(order_data)

print(f"Order: {order.order_id}")
for item in order.items:
    line_total = item.quantity * item.unit_price
    print(f"  {item.name} x {item.quantity}  =  ${line_total:.2f}")

Output:

Order: ORD-001
  Mechanical Keyboard x 1  =  $89.99
  USB-C Hub x 2  =  $59.98

Each element in the items list is a fully validated OrderItem instance. If any item in the list has a bad value, Pydantic reports the exact index and field that failed.

Optional nested models

Mark a nested model as optional by using ModelName | None = None:

from pydantic import BaseModel

class Discount(BaseModel):
    code:    str
    percent: float

class Order(BaseModel):
    order_id: str
    total:    float
    discount: Discount | None = None   # Optional nested model

# Works without a discount
order = Order(order_id="ORD-001", total=99.99)
print(order.discount)   # None

# Also works when a discount is provided as a dict
order = Order(
    order_id="ORD-002",
    total=99.99,
    discount={"code": "SAVE20", "percent": 20.0},
)
print(order.discount.code)      # SAVE20
print(order.discount.percent)   # 20.0

Pydantic accepts either a Discount instance or a plain dictionary for an optional nested field. Both are validated the same way — so you can pass raw API data without constructing objects manually.

Serializing nested models

When you call .model_dump() or .model_dump_json(), Pydantic recursively serializes all nested models too:

from pydantic import BaseModel

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

class User(BaseModel):
    id:      int
    name:    str
    address: Address

user = User(
    id=1,
    name="Alice Smith",
    address=Address(street="123 Main St", city="Amsterdam", country="Netherlands"),
)

print(user.model_dump())
# {
#   'id': 1,
#   'name': 'Alice Smith',
#   'address': {'street': '123 Main St', 'city': 'Amsterdam', 'country': 'Netherlands'}
# }

print(user.model_dump_json(indent=2))

Output of model_dump_json:

{
  "id": 1,
  "name": "Alice Smith",
  "address": {
    "street": "123 Main St",
    "city": "Amsterdam",
    "country": "Netherlands"
  }
}

Real-world example: Order with Customer and line items

Here is the kind of model hierarchy you’d encounter in a real e-commerce API. An Order contains a Customer (who has a billing Address), a list of OrderItem objects, and an optional Discount:

from pydantic import BaseModel, Field
from datetime import datetime

class Address(BaseModel):
    street:  str
    city:    str
    country: str
    postcode: str | None = None

class Customer(BaseModel):
    customer_id:      int
    name:             str
    email:            str
    billing_address:  Address
    shipping_address: Address | None = None  # Falls back to billing if absent

class OrderItem(BaseModel):
    product_id: str
    name:       str
    quantity:   int   = Field(gt=0)
    unit_price: float = Field(gt=0.0)

    @property
    def line_total(self) -> float:
        return round(self.quantity * self.unit_price, 2)

class Order(BaseModel):
    order_id:   str
    created_at: datetime
    customer:   Customer
    items:      list[OrderItem]
    notes:      str | None = None

# Simulating a complete API request body
payload = {
    "order_id": "ORD-20250601-042",
    "created_at": "2025-06-01T14:32:00Z",
    "customer": {
        "customer_id": 7,
        "name": "Alice Smith",
        "email": "[email protected]",
        "billing_address": {
            "street": "123 Main St",
            "city": "Amsterdam",
            "country": "Netherlands",
            "postcode": "1011 AB",
        },
    },
    "items": [
        {"product_id": "SKU-A1", "name": "Mechanical Keyboard", "quantity": 1, "unit_price": 89.99},
        {"product_id": "SKU-B7", "name": "USB-C Hub",           "quantity": 2, "unit_price": 29.99},
    ],
    "notes": "Please leave at the door.",
}

order = Order.model_validate(payload)

# Navigate the object graph with full IDE support
print(f"Order:    {order.order_id}")
print(f"Customer: {order.customer.name} ({order.customer.email})")
print(f"City:     {order.customer.billing_address.city}")
print()
for item in order.items:
    print(f"  {item.name:<25} x{item.quantity}  ${item.line_total:.2f}")

grand_total = sum(item.line_total for item in order.items)
print(f"\nGrand total: ${grand_total:.2f}")

Output:

Order:    ORD-20250601-042
Customer: Alice Smith ([email protected])
City:     Amsterdam

  Mechanical Keyboard       x1  $89.99
  USB-C Hub                 x2  $59.98

Grand total: $149.97

Notice that the created_at field is typed as datetime. Pydantic automatically parses the ISO 8601 string "2025-06-01T14:32:00Z" into a proper datetime object — no manual parsing required.

How nested models map to API schemas

This nesting pattern maps directly to how real API request and response bodies look. When you use FastAPI, you define your endpoint’s input type as a nested Pydantic model, and FastAPI:

Reads the incoming JSON body
Validates it against your model hierarchy
Hands your endpoint function a fully typed, validated object
Generates JSON Schema for the /docs page automatically

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# The same models you've already defined...
@app.post("/orders")
def create_order(order: Order) -> dict:
    # 'order' is a fully validated Order object
    return {"order_id": order.order_id, "status": "created"}

Your Pydantic model is your API schema. You define it once and get validation, documentation, and serialization for free.

Reusing models across your codebase

Defining small, focused models and composing them lets you avoid repetition:

from pydantic import BaseModel

class Money(BaseModel):
    amount:   float
    currency: str = "USD"

class Product(BaseModel):
    sku:   str
    name:  str
    price: Money         # Reuse Money anywhere a monetary value appears

class Invoice(BaseModel):
    line_items: list[Product]
    subtotal:   Money
    tax:        Money
    total:      Money

Each model stays small and testable on its own, and you compose them into arbitrarily complex structures.

Ready to manage application configuration?

You now know how to model any hierarchical data structure — from a single nested object to a multi-level object graph with optional branches and lists. Next, learn how to load type-safe configuration for your application from environment variables and .env files.

Pydantic Settings

Read environment variables and .env files into a validated, type-safe Settings object.

Core Python

Advanced Python

Pydantic

Nested Pydantic Models for Complex Data Structures

Using a model as a field type

Parsing nested data from a dictionary

Lists of models

Optional nested models

Serializing nested models

Real-world example: Order with Customer and line items

How nested models map to API schemas

Reusing models across your codebase

Ready to manage application configuration?

Pydantic Settings

​Using a model as a field type

​Parsing nested data from a dictionary

​Lists of models

​Optional nested models

​Serializing nested models

​Real-world example: Order with Customer and line items

​How nested models map to API schemas

​Reusing models across your codebase

​Ready to manage application configuration?

Pydantic Settings

Using a model as a field type

Parsing nested data from a dictionary

Lists of models

Optional nested models

Serializing nested models

Real-world example: Order with Customer and line items

How nested models map to API schemas

Reusing models across your codebase

Ready to manage application configuration?