Nested Pydantic Models: Composing Complex Data

Why it exists

Real-world data is rarely flat. APIs and configuration files often have structured, hierarchical data, like a JSON object nested inside another. Nested models provide a way to represent and validate this entire structure in your code, ensuring the whole data tree is correct, not just the top-level keys.

The mental model

Think of Pydantic models as custom data types you invent. Just as you can have a list of ints, a field in one model can be another model, like a User model. You are composing data structures like Lego bricks, where each brick is a self-contained, validated unit. The parent model delegates validation for a subsection of the data to the appropriate child model.

How it works

You define two or more classes that inherit from BaseModel. Then, in the parent model, you declare a field and use the child model's class name as the type hint. For example, class User(BaseModel): ... and class Account(BaseModel): owner: User. When you create an Account instance from a dictionary, Pydantic expects the owner key to contain a dictionary that it can, in turn, parse and validate using the User model. This process is recursive and works for arbitrarily deep data structures.

When to use it

Use nested models whenever you are handling data that has a natural hierarchy. This is the standard pattern in web development with JSON APIs. For example, a BlogPost model that has an Author object and a list of Comment objects. It is also useful for complex configuration files where settings are grouped into logical sections.

When not to use it

Avoid nesting if the data relationship is truly flat; don't create a nested model for a single field if a simple type like str works, as it adds unnecessary complexity. Also, be mindful of circular dependencies (Model A needs Model B, and Model B needs Model A). While Pydantic can handle this, it can make code harder to reason about and may indicate your data model needs simplification.

One canonical example

Imagine an API for a library. Instead of putting all author details directly in a book model, you create two models. First, an Author model: class Author(BaseModel): name: str; birth_year: int. Second, a Book model that uses it: class Book(BaseModel): title: str; author: Author. When parsing the JSON {'title': 'Pydantic Deep Dive', 'author': {'name': 'Alex', 'birth_year': 1990}}, Pydantic creates the Book object, sees the author field, and then uses the Author model to parse the inner dictionary, guaranteeing both the book and its author are valid.