Pydantic Serialization with model_dump addresses a recurring problem in Python projects: Turn validated models into dictionaries or JSON under an explicit output contract. This guide explains the mechanism, provides an executable example, and identifies the boundaries that keep an implementation reliable.
Concept and use case
model_dump returns a dictionary; json mode converts values to serializable types. model_dump_json emits JSON text using model rules.
For the related fundamentals, also read the Pydantic guide. Integration stays simpler when functions receive dependencies and data explicitly instead of relying on global state.
Practical example
from datetime import datetime
from pydantic import BaseModel, Field, field_serializer
class UserOut(BaseModel):
id: int
display_name: str = Field(serialization_alias="name")
created_at: datetime
@field_serializer("created_at")
def serialize_date(self, value: datetime) -> str:
return value.isoformat()
payload = user.model_dump(mode="json", by_alias=True)Create dedicated output models at public boundaries. Treat include and exclude as extra protection, not a substitute for a clear schema.
Important decisions
The correct choice depends on the public contract, expected volume, and failure behavior.
Consider concurrency, empty inputs, and partial failures. Document every limit that affects consumers and choose names that express intent.
Common mistakes
A minimal example does not replace bounds, error handling, and observability. Serializing an internal model directly may expose password hashes or administrative flags. Inconsistent aliases silently break consumers.
Avoid catching exceptions without context or returning partial output as if it were complete. An explicit failure is usually safer than silently incorrect data.
How to validate
Validate behavior, not only the happy path. Assert the exact payload, dates, enums, aliases, optional fields, and deliberate absence of sensitive information.