Pydantic V2 Deep Dive: Building Immutable, Recursive, and Interdependent Data Architectures

BACKEND SERIES

Day 30: The Immutable State — Complex Schemas & Serialization with Pydantic V2

15 min read

Series: Logic & Legacy

Day 30 / 50 (Part 2 of 2)

Level: Senior / Architect

In this guide, you will transcend individual field constraints. You will learn how to validate interdependent fields, safely bridge frontend camelCase with backend snake_case, filter complex serialization dumps, and enforce strict, immutable data architectures using Pydantic V2's advanced model configurations.

⏳  Yesterday, we built the iron gate. We restricted strings, validated numbers, and secured individual fields from coercion bugs. But enterprise objects do not exist in isolation. Passwords must match their confirmations. API payloads arrive using foreign naming conventions. deeply nested JSON graphs need recursive validation. Today, we shift from validating discrete variables to orchestrating complex, interdependent, and immutable data structures.

1. Interdependent Fields (@model_validator)

When a validation rule depends on comparing two or more fields within the same payload (e.g., ensuring "Password" and "Confirm Password" match, or that "End Date" comes after "Start Date"), you cannot use a simple @field_validator. You must step back and evaluate the entire model using @model_validator.

Example 1: Cross-Field Validation

from pydantic import BaseModel, model_validator, ValueError
from typing import Self

class Registration(BaseModel):
    password: str
    confirm_password: str

    # mode='after' means basic type checks have already passed
    @model_validator(mode='after')
    def check_passwords_match(self) -> Self:
        if self.password != self.confirm_password:
            # Always raise ValueError so Pydantic catches it
            raise ValueError('Passwords do not match')
        return self

Crucial Rule: If you raise a custom Python exception (e.g., raise MyCustomError), Pydantic will NOT wrap it in a standard HTTP-friendly ValidationError. It will native-crash your app. Always raise ValueError or AssertionError inside validators.

2. Computed Fields and Derived Data

Often, your API needs to return data that isn't stored directly but is calculated from other fields. By combining standard Python properties with Pydantic's @computed_field, you guarantee this derived data is automatically included when serializing the model to JSON.

Example 2: Dynamic Computed Properties

from pydantic import BaseModel, computed_field

class User(BaseModel):
    first: str
    last: str

    @computed_field
    @property
    def display_name(self) -> str:
        return f"{self.first} {self.last}"

Architectural Warning: Computed fields execute dynamically every time .model_dump() is called. If you put heavy logic inside them (like a database query), you will bottleneck your serialization pipeline.

3. Nested Schemas & Recursive Parsing

Real-world JSON is a deep tree, not a flat list. You can use Pydantic models as type hints inside other Pydantic models. When parsing nested dictionaries using model_validate(), Pydantic handles the recursion seamlessly.

Example 3: Validating Deep Trees

from pydantic import BaseModel

class Comment(BaseModel):
    text: str

class Post(BaseModel):
    title: str
    comments: list[Comment]  # Nested validation

raw_data = {
    "title": "Hello",
    "comments": [{"text": "First!"}, {"text": "Great post!"}]
}
# Replaces keyword unpacking (**kwargs) for complex dicts
post = Post.model_validate(raw_data)

If a deeply nested item fails validation, Pydantic's error trace is a lifesaver. It provides a loc (location) array (e.g., loc: ('comments', 1, 'text')), pinpointing exactly which nested item in the list triggered the failure.

The Mental Model: The Translators at the Border

Imagine an API gateway as a border crossing. The Javascript frontend speaks exclusively in camelCase (e.g., userId). But standard Python strictly demands snake_case (e.g., user_id). Without Aliases, you would have to write hundreds of lines of dictionary manipulation to translate keys manually before validation. Aliases are border translators—they intercept the foreign language, translate it instantly to Python, and allow your core application to remain pure.

4. Aliasing and Naming Conventions

To implement these "translators," we use the alias parameter in the Field definition. Furthermore, to make our lives easier during testing and internal development, we use populate_by_name=True so we aren't forced to use the frontend's naming convention in our backend code.

Example 4: Bridging the Naming Divide

from pydantic import BaseModel, Field, ConfigDict

class User(BaseModel):
    # populate_by_name allows us to use either 'id' or 'uid' during creation
    model_config = ConfigDict(populate_by_name=True)
    
    # Maps the incoming JSON key "id" to our internal Python variable "uid"
    uid: int = Field(alias="id")

# Both of these now work perfectly
user1 = User(id=1)   # How an API payload creates it
user2 = User(uid=2)  # How you create it in a Python test

When sending data back to the frontend, simply call user.model_dump(by_alias=True) to automatically convert your Python uid back into the JSON id.

"A vow once spoken cannot be unsaid, and truth once established must not shift with the wind. An architecture built on mutable states invites chaos and unseen modifications. Freeze your models. Let data be a historical record, immutable and absolute."

5. The Absolute Strictness: Disabling Coercion & Extra Fields

There are times—especially in financial or security systems—where Pydantic's default "lax" coercion is dangerous. If you expect an integer, and the client sends the float 12.0, you want the request to violently fail. Furthermore, you want to reject any payload that includes unexpected dictionary keys (preventing parameter injection attacks).

Example 5: The Fortress Configuration

from pydantic import BaseModel, ConfigDict

class SecurePayload(BaseModel):
    # strict=True: No string-to-int coercion allowed at all.
    # extra='forbid': Any undocumented key in the JSON raises an error.
    model_config = ConfigDict(strict=True, extra='forbid')
    
    amount: int

# Fails because "100" is a string, not an int
# Payload(amount="100") 

# Fails because 'currency' is an undocumented "extra" field
# Payload(amount=100, currency="USD")

6. Creating Immutable Data Architectures

By default, Pydantic only validates data upon instantiation. If you later write user.email = "not-an-email", it does not check it! You can fix this with validate_assignment=True. However, the true hallmark of a senior architecture is embracing functional programming concepts: Immutability.

If you set frozen=True, the model is completely locked after creation. This guarantees thread safety, prevents side-effect bugs, and allows the model to be hashed (meaning it can be used as a key in a dictionary or put into a set()).

Example 6: Frozen State

from pydantic import BaseModel, ConfigDict

class AppConfig(BaseModel):
    model_config = ConfigDict(frozen=True)
    api_key: str

config = AppConfig(api_key="123")

# Raises a ValidationError: Instance is frozen!
# config.api_key = "456"

🛠️ Day 30 Workshop: The Final API Schema

Let's combine everything from Day 29 and Day 30 into a single, production-ready response model. It parses a raw JSON string, translates aliases, checks complex logic, and freezes the result.

Example 7: The Master Configuration

from pydantic import BaseModel, ConfigDict, Field, model_validator
from typing import Self

class DateRange(BaseModel):
    model_config = ConfigDict(
        frozen=True, 
        populate_by_name=True,
        extra='forbid'
    )
    
    start: int = Field(alias="startDateUnix")
    end: int = Field(alias="endDateUnix")

    @model_validator(mode='after')
    def validate_timeline(self) -> Self:
        if self.end <= self.start:
            raise ValueError("End date must be strictly after start date")
        return self

# Parse raw JSON directly from a string (bypassing json.loads)
json_string = '{"startDateUnix": 170000, "endDateUnix": 170050}'
valid_range = DateRange.model_validate_json(json_string)

# Serialize it back, dropping the aliases, excluding start time
dump = valid_range.model_dump(by_alias=False, exclude={'start'})

🔥 PRO UPGRADE / TEASER

Our data is now immutable, rigorously validated, and perfectly serialized. We have completely conquered the application layer. But models in RAM disappear when the server restarts. Tomorrow, we bridge the gap between Python and Persistence. Welcome to Day 31: SQLAlchemy 2.0 & The Object Relational Mapper (ORM).

Architectural Consulting

If you are building a data-intensive AI application and require a Senior Engineer to architect your secure, high-concurrency backend, I am available for direct contracting.

Explore Enterprise Engagements →

← Previous

Day 29: Pydantic (Part 1)

Next →

Day 31: SQLAlchemy 2.0