Nested models in FastAPI - Step-by-Step Execution

Concept Flow - Nested models

Define Base Model

↓

Define Nested Model

↓

Use Nested Model as Field in Parent Model

↓

Create Instance of Parent Model

↓

Validate Nested Data Automatically

↓

Access Nested Data via Parent Instance

Shows how a model contains another model as a field, enabling structured nested data validation.

Execution Sample

FastAPI

from pydantic import BaseModel

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

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

Defines a User model with a nested Address model to validate structured user data.

Execution Table

Step	Action	Input Data	Validation Result	Output Instance
1	Define Address model	N/A	Model created	Address class ready
2	Define User model with Address field	N/A	Model created	User class ready
3	Create User instance with nested dict	{'name': 'Alice', 'address': {'city': 'Paris', 'country': 'France'}}	Valid data	User(name='Alice', address=Address(city='Paris', country='France'))
4	Access nested field	user.address.city	Returns 'Paris'	'Paris'
5	Create User instance with invalid nested data	{'name': 'Bob', 'address': {'city': 123, 'country': 'USA'}}	Validation error: city must be str	Error raised

💡 Execution stops after validation error on nested model field type mismatch.

Variable Tracker

Variable	Start	After Step 3	After Step 4	After Step 5
user	undefined	User(name='Alice', address=Address(city='Paris', country='France'))	User(name='Alice', address=Address(city='Paris', country='France')) (accessed nested city)	Error raised, no valid user instance

Key Moments - 2 Insights

Why does the nested 'address' field accept a dictionary when creating a User?

Because Pydantic automatically converts nested dictionaries into the nested model instances, as shown in execution_table step 3.

What happens if the nested data type is wrong, like city being a number?

Validation fails and raises an error, stopping instance creation, as shown in execution_table step 5.

Visual Quiz - 3 Questions

Look at the execution table, what is the value of user.address.city after step 4?

A 'Paris'

B 'France'

C 123

D Error

💡 Hint

Check the Output Instance column at step 4 where nested field is accessed.

At which step does validation fail due to wrong nested data type?

A Step 3

B Step 5

C Step 4

D No failure

💡 Hint

Look for 'Validation error' in the Validation Result column.

If the Address model had an extra field 'zipcode', what would happen when creating User without it?

A zipcode defaults to None automatically

B User instance created ignoring zipcode

C Validation error for missing zipcode

D No effect, zipcode is optional by default

💡 Hint

Pydantic requires all fields unless given defaults; see validation behavior in steps 3 and 5.

Concept Snapshot

Nested models in FastAPI use Pydantic models inside other models.
Define a model (e.g., Address), then use it as a field in another model (e.g., User).
When creating the parent model, nested dicts convert automatically to nested model instances.
Validation applies recursively, so nested data must match expected types.
Access nested data via dot notation (user.address.city).
Validation errors stop instance creation if nested data is invalid.

Full Transcript

This visual execution trace shows how nested models work in FastAPI using Pydantic. First, we define a simple Address model with city and country fields. Then, we define a User model that includes an Address as a nested field. When creating a User instance, we can pass a dictionary for the address, and Pydantic automatically converts it into an Address instance. Accessing nested fields like user.address.city returns the expected values. If nested data types are wrong, such as city being a number instead of a string, validation fails and raises an error, preventing instance creation. This ensures data is structured and validated deeply, making nested models powerful for complex data shapes.