Api-Development on Shane's Personal Blog

Litestar DTOs: The 'Advanced Feature' I Didn't Need (And When You Might)

Sun, 02 Nov 2025 00:00:00 GMT

The Moment of Self-Doubt

I was knee-deep in my FastAPI to Litestar migration, feeling pretty good about myself. I’d just wrapped my head around msgspec and was happily writing explicit schema conversions. Everything was working beautifully.

Then I made the mistake of looking at Litestar’s full-stack example repository.

class UserDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash", "sessions", "oauth_accounts"},
        rename_strategy="camel",
        max_nested_depth=2,
    )

@get("/users/{user_id}", return_dto=UserDTO)
async def get_user(self, user_id: UUID) -> User:
    return await user_service.get(user_id)

Wait. What?

The controller just returns the raw SQLAlchemy model? No manual conversion? No explicit schema class? Just… return the model and some magic DTO thing handles everything?

And everyone in the examples was using it. Every. Single. Endpoint.

That familiar developer anxiety crept in: Am I doing this wrong?

My “Primitive” Approach

Here’s what I’d been doing, blissfully unaware I might be committing some architectural sin:

# Define explicit response schemas
class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    full_name: str | None = None
    is_admin: bool = False

# Manual conversion in controllers
@get("/profile")
async def profile(self, current_user: AppUser) -> UserResponse:
    return UserResponse(
        id=current_user.id,
        email=current_user.email,
        full_name=current_user.full_name,
        is_admin=current_user.is_admin,
    )

It worked. It was clear. I could see exactly what data was being exposed.

But now I was looking at this DTO thing thinking: “Should I be using that instead? Is my code… amateur hour?”

The Investigation Begins

I did what any self-respecting developer does when feeling inadequate: I asked ChatGPT.

“Should I be using Litestar’s DTO system instead of explicit msgspec schemas?”

The conversation that followed was enlightening. It wasn’t a simple “yes” or “no”—it was a “depends on what you’re building.”

That’s when I realized I needed to actually understand what DTOs are and what problem they solve. Because apparently, not every “advanced feature” is automatically better.

What Even IS a DTO?

DTO stands for Data Transfer Object. In Litestar’s context, it’s a transformation layer between your internal data models (SQLAlchemy, Pydantic, msgspec) and what you send/receive over the wire.

Think of it as a smart template system. You define transformation rules once, and Litestar applies them automatically:

“Exclude these sensitive fields”
“Rename snake_case to camelCase”
“Only include these specific fields”
“Serialize nested relationships up to depth 2”

Instead of writing manual conversion code in every endpoint, you configure the DTO once and attach it to your routes.

The key insight: DTOs are platform-agnostic. They work with Pydantic models, msgspec structs, dataclasses, and SQLAlchemy models through different backends (PydanticDTO, MsgspecDTO, SQLAlchemyDTO). The concept remains the same regardless of which you use.

But here’s what I was really wondering: Do I actually need this?

The Side-by-Side Reality Check

Let me show you what I was comparing. Here’s a real endpoint from my auth system:

My Current Approach (Explicit Schemas)

# schemas.py - Define exactly what to expose
class LoginRequest(CamelizedBaseStruct):
    email: str
    password: str

class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    full_name: str | None = None
    is_admin: bool = False

class LoginResponse(CamelizedBaseStruct):
    access_token: str
    token_type: str = "Bearer"
    expires_in: int
    user: UserResponse

# controller.py
@post("/login")
async def login(
    self,
    data: LoginRequest,
    user_service: UserService,
) -> LoginResponse:
    user = await user_service.authenticate(data.email, data.password)
    token = create_access_token(user.id)

    return LoginResponse(
        access_token=token,
        expires_in=3600,
        user=UserResponse(
            id=user.id,
            email=user.email,
            full_name=user.full_name,
            is_admin=user.is_admin,
        ),
    )

Line count: Clear, explicit, about 35 lines total.

The DTO Approach

# schemas.py - Configure transformation rules
class UserResponseDTO(SQLAlchemyDTO[AppUser]):
    config = DTOConfig(
        exclude={"password_hash", "sessions", "oauth_accounts", "credit_balance"},
        rename_strategy="camel",
    )

class LoginRequestDTO(MsgspecDTO[LoginRequest]):
    config = DTOConfig(rename_strategy="camel")

# controller.py
@post("/login", data=LoginRequestDTO, return_dto=UserResponseDTO)
async def login(
    self,
    data: DTOData[LoginRequest],
    user_service: UserService,
) -> AppUser:
    request = data.create_instance()
    user = await user_service.authenticate(request.email, request.password)
    # ... token creation
    return user  # DTO handles conversion

Looking at these side-by-side, the DTO version seemed… more complex? Not simpler?

For my use case:

4 fields in the request
4 fields in the user response
Different fields in each response type (login vs profile vs admin)

The DTO configuration wasn’t saving me any code. If anything, it was adding abstraction for no clear benefit.

The Lightbulb Moment

Then ChatGPT gave me an example that made everything click.

“Imagine you have a User model with 30 fields, and you have 10 different endpoints that return users with only slight variations.”

Oh.

Without DTOs:

class UserListResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    username: str
    full_name: str
    # ... 26 more fields
    created_at: datetime
    updated_at: datetime

class UserDetailResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    username: str
    full_name: str
    # ... 26 more fields (SAME AS ABOVE)
    created_at: datetime
    updated_at: datetime
    last_login_at: datetime  # ONE extra field
    login_count: int          # ONE extra field

class UserAdminResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    username: str
    full_name: str
    # ... 26 more fields (SAME AS ABOVE AGAIN)
    created_at: datetime
    updated_at: datetime
    last_login_at: datetime
    login_count: int
    password_hash: str  # Admin can see this

You’d be copying and pasting 28 fields across three schemas. If you need to add a new field or rename one, you’d have to update it in three places. Error-prone. Painful during refactoring.

With DTOs:

# Define base fields once via the model
# Then configure variations

class UserListDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash", "last_login_at", "login_count"},
        rename_strategy="camel",
    )

class UserDetailDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash"},
        rename_strategy="camel",
    )

class UserAdminDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        rename_strategy="camel",  # Include everything
    )

Ah. Now I see it.

DTOs shine when you have large schemas with small variations. Instead of copying 30 fields and playing “spot the difference” during code reviews, you define transformations: “include everything except X” or “exclude only Y.”

But my auth endpoints? 4-8 fields, completely different shapes. No duplication to eliminate. No variations to configure.

When DTOs Actually Make Sense

Once I understood the problem DTOs solve, I could see exactly when they’d be valuable:

1. Large Schemas with Minor Variations

Perfect for:

User models with 20+ fields
Product catalogs with extensive metadata
Admin panels with many similar CRUD endpoints

# One model, many views
class ProductListDTO(SQLAlchemyDTO[Product]):
    config = DTOConfig(
        exclude={"internal_cost", "supplier_details", "inventory_history"},
    )

class ProductDetailDTO(SQLAlchemyDTO[Product]):
    config = DTOConfig(
        exclude={"internal_cost", "supplier_details"},  # Show more
    )

class ProductAdminDTO(SQLAlchemyDTO[Product]):
    config = DTOConfig()  # Show everything

Instead of defining 30 fields three times, you configure what to exclude.

2. Complex Nested Relationships

When you have models that reference other models:

# Model structure
class Case(Base):
    id: UUID
    name: str
    user: Mapped[User]  # Relationship
    documents: Mapped[list[Document]]  # Relationship
    workflow_task: Mapped[WorkflowTask]  # Relationship

# Without DTO - manual nesting
class DocumentResponse(CamelizedBaseStruct):
    id: UUID
    filename: str

class WorkflowTaskResponse(CamelizedBaseStruct):
    id: UUID
    stage: str

class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str

class CaseResponse(CamelizedBaseStruct):
    id: UUID
    name: str
    user: UserResponse
    documents: list[DocumentResponse]
    workflow_task: WorkflowTaskResponse

# Manual conversion - tedious and error-prone
@get("/cases/{case_id}")
async def get_case(self, case_id: UUID) -> CaseResponse:
    case = await case_service.get(case_id)
    return CaseResponse(
        id=case.id,
        name=case.name,
        user=UserResponse(id=case.user.id, email=case.user.email),
        documents=[
            DocumentResponse(id=doc.id, filename=doc.filename)
            for doc in case.documents
        ],
        workflow_task=WorkflowTaskResponse(
            id=case.workflow_task.id,
            stage=case.workflow_task.stage,
        ),
    )

That’s a lot of manual mapping!

With DTOs:

class CaseDTO(SQLAlchemyDTO[Case]):
    config = DTOConfig(
        max_nested_depth=2,  # Auto-serialize relationships
        rename_strategy="camel",
    )

@get("/cases/{case_id}", return_dto=CaseDTO)
async def get_case(self, case_id: UUID) -> Case:
    return await case_service.get(case_id)  # DTO handles nesting

The DTO automatically serializes nested relationships. The resulting JSON preserves the structure:

{
  "id": "123...",
  "name": "Smith v. Jones",
  "user": {
    "id": "456...",
    "email": "lawyer@example.com",
    "fullName": "John Lawyer"
  },
  "documents": [{ "id": "789...", "filename": "contract.pdf" }],
  "workflowTask": {
    "id": "012...",
    "stage": "completed"
  }
}

For deeply nested structures, DTOs eliminate a LOT of boilerplate.

3. Consistent Transformations Across Many Endpoints

If you have 20 endpoints that all return the same data with the same transformations:

# Without DTO - repeat rename logic everywhere
class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    full_name: str  # Manually renamed from fullName
    is_admin: bool  # Manually renamed from isAdmin

# With DTO - configure once
class UserDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        rename_strategy="camel",  # Applies to all fields automatically
    )

If you later decide to use PascalCase instead of camelCase, you change one config line instead of 20 schema classes.

4. Bidirectional Use (Request + Response)

DTOs can handle both input validation and output serialization:

class UserCreateDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        include={"email", "password", "full_name"},  # Only these for creation
        rename_strategy="camel",
    )

class UserResponseDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash"},  # Don't expose sensitive fields
        rename_strategy="camel",
    )

@post("/users", data=UserCreateDTO, return_dto=UserResponseDTO)
async def create_user(self, data: DTOData[User]) -> User:
    user_data = data.as_builtins()  # Validated dict
    user = await user_service.create(user_data)
    return user  # Auto-converted to response

Same model, different “views” for input vs output.

The Feature Buffet: What DTOs Can Do

Now that I understood when to use DTOs, I explored what they could actually do. Here are the key capabilities (without getting into syntax details):

Field Control:

Exclude fields: Hide sensitive data like password_hash, internal_notes
Include only specific fields: Whitelist approach instead of blacklist
Partial models: Make all fields optional (useful for PATCH endpoints)

Transformations:

Rename strategy: Convert between snake_case, camelCase, PascalCase
Rename individual fields: Custom mappings for specific fields
Computed fields: Add calculated values not in the model

Relationship Handling:

Max nested depth: Control how deep relationship serialization goes
Circular reference handling: Prevent infinite loops in self-referential models

Validation:

Type safety: DTOData provides validated conversion helpers
Integration with model validators: Works with Pydantic/msgspec validation

The point isn’t to memorize all these options—it’s to recognize that DTOs are a configuration system for data transformation. When you have complex transformation needs across many endpoints, that configuration approach starts to pay off.

The Honest Trade-offs

After all this investigation, I could finally see both sides clearly.

When DTOs Win

Scenario: E-commerce admin panel with 50+ endpoints, User/Product/Order models with 25+ fields each

✅ Less code duplication (define fields once)
✅ Consistent transformations (one rename_strategy for all)
✅ Safer refactoring (change model, DTOs adapt)
✅ Automatic nested serialization (complex object graphs)
✅ Centralized field exclusion (security by default)

Pain points: More abstraction, harder debugging when things go wrong, learning curve for DTOConfig

When Explicit Schemas Win

Scenario: Auth system with 8 endpoints, small distinct request/response shapes

✅ Crystal clear what data is exposed (security-critical)
✅ Simple debugging (no transformation layer)
✅ Easy to understand (explicit is better than implicit)
✅ Perfect for small, distinct schemas
✅ Full control over every field

Pain points: Manual conversion code, potential field drift if you’re not careful, more code for large schemas

My Decision: Explicit Schemas (For Now)

For my auth system, the choice became obvious:

My schemas are:

Small (4-8 fields)
Distinct (login, register, profile all have different shapes)
Security-critical (I want to be VERY explicit about what’s exposed)

My team values:

Explicitness over magic
Simple debugging
Clear code over clever code

DTOs would add complexity without solving any problem I actually have.

But here’s the key realization: This isn’t a forever decision.

If I later build:

An admin dashboard with 30 similar CRUD endpoints
A reporting system with complex nested data
A public API with many variations of User/Product responses

Then DTOs would make perfect sense. I’ll know when I need them—when I find myself copy-pasting large schemas and playing “spot the difference” during code reviews.

The Real Lesson: Question the “Best Practices”

This whole journey taught me something more valuable than just when to use DTOs.

I started feeling inadequate because I wasn’t using an “advanced feature” everyone else seemed to be using. The example code used it, so clearly I was doing something wrong, right?

Wrong.

“Advanced features” aren’t better—they’re just tools for specific problems.

The Litestar examples use DTOs because they’re showing off the framework’s capabilities. They’re demonstrating what’s possible, not what’s mandatory. A full-stack example repository naturally has complex nested data and many similar endpoints—the perfect use case for DTOs.

But your codebase might be different. And that’s okay.

The best code isn’t the one that uses the most advanced features. It’s the one that:

Solves your actual problems
Your team can understand and maintain
Fits your specific context

Sometimes that means reaching for powerful abstraction layers like DTOs. Sometimes it means writing simple, explicit conversion code.

The skill isn’t in knowing all the tools—it’s in knowing which tool fits which problem.

How to Choose for Your Project

Here’s the decision framework I landed on:

Use Explicit Schemas When

Schemas are small (< 15 fields)
Each endpoint has distinct response shapes
Security is critical (auth, payments, PII)
Team is small or values explicitness
You’re building a simple CRUD API

Use DTOs When

Schemas are large (> 20 fields)
Many endpoints return similar data with slight variations
Complex nested relationships need serialization
You have 20+ endpoints with consistent transformations
You’re building an admin panel or complex dashboard
Field exclusion/security is error-prone without automation

Don’t Decide Yet If

You’re just starting the project. Build a few endpoints with explicit schemas first. If you find yourself copy-pasting large schemas and thinking “there has to be a better way,” that’s when you look into DTOs.

Don’t add abstraction until you feel the pain it’s meant to solve.

Where I Am Now

I’m still using explicit msgspec schemas for my auth system. No DTOs. No automatic transformations. Just clear, simple conversion code.

And I’m completely confident in that decision.

Not because DTOs are bad—they’re actually quite elegant for the right use case. But because I understand why they exist and when they help.

That moment of self-doubt when I saw the example code using DTOs? It turned into a learning opportunity. I don’t feel inadequate anymore. I feel informed.

When I eventually build that admin dashboard with 50 endpoints and complex nested data, I’ll reach for DTOs with confidence. I’ll know exactly why I’m using them and how to configure them effectively.

But for now? Explicit is exactly right.

The Takeaway

Next time you see an “advanced feature” in example code and wonder if you’re doing it wrong by not using it, remember:

Understand the problem it solves - What pain point does this feature address?
Evaluate if you have that problem - Do you actually need this solution?
Consider the trade-offs - What are you gaining vs. what complexity are you adding?
Choose what fits your context - There’s no one-size-fits-all “best practice”

Sometimes the simple approach is the right approach. And that’s not a failure—it’s good engineering judgment.

DTOs are a powerful tool for data transformation at scale. But power you don’t need is just complexity you have to maintain.

Know your tools. Understand their trade-offs. Choose wisely.

(Written by Human, improved using AI where applicable.)

From Pydantic to msgspec: A Migration Story About Validation and Control

Sun, 02 Nov 2025 00:00:00 GMT

The Migration That Made Me Question Everything

I thought I had Python validation figured out. Pydantic was my trusted companion—elegant, powerful, and seemingly complete. Why would I need anything else?

Then I decided to migrate a project from FastAPI to Litestar. The reasons were good: better performance, cleaner architecture, advanced SQLAlchemy integration. But there was a catch—Litestar favored msgspec over Pydantic. And msgspec? I’d barely heard of it.

“How hard could it be?” I thought. “Validation is validation, right?”

Wrong. So wrong.

The Pydantic Comfort Zone

Let me show you what I was used to. Here’s how I’d been writing validation for years:

from pydantic import BaseModel, EmailStr, field_validator

class UserRegistration(BaseModel):
    email: EmailStr  # Automatic email validation
    password: str
    age: int

    @field_validator('password')
    @classmethod
    def validate_password(cls, v: str) -> str:
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        if not any(c.isupper() for c in v):
            raise ValueError('Password must contain uppercase letter')
        return v

    @field_validator('age')
    @classmethod
    def validate_age(cls, v: int) -> int:
        if v < 18:
            raise ValueError('Must be 18 or older')
        return v

# Usage in FastAPI
@app.post("/register")
async def register(data: UserRegistration):
    # If we get here, data is GUARANTEED valid
    # Everything is checked: types, email format, password rules, age
    user = await create_user(data.model_dump())
    return {"message": "User created"}

Beautiful, right? One model definition, all validation in one place. The moment you create a UserRegistration instance, Pydantic validates everything—types, formats, business rules. If the data reaches your endpoint handler, you know it’s valid.

This felt complete. Elegant. Right.

First Contact: Where Are My Validators?

Fast forward to my Litestar migration. I started converting my Pydantic models to msgspec:

import msgspec

class UserRegistration(msgspec.Struct):
    email: str
    password: str
    age: int

# Usage in Litestar
@post("/register")
async def register(data: UserRegistration) -> dict:
    # Wait... where do I put the email validation?
    # Where's my password strength check?
    # How do I validate age >= 18?
    user = await create_user(msgspec.to_builtins(data))
    return {"message": "User created"}

I stared at the screen, confused. Where were the decorators? Where was EmailStr? How do I add my custom validators?

I spent an embarrassing amount of time searching for “msgspec field_validator equivalent” and finding… nothing helpful.

My first thought: “This library is incomplete. How can people use this?”

My second thought: “Maybe I’m missing something.”

Spoiler: I was missing something big.

The Uncomfortable Truth: Validation Comes in Two Flavors

After hours of frustration (and reading way too much documentation), I had a realization: msgspec and Pydantic have fundamentally different philosophies about what validation means.

Here’s what finally clicked for me:

Pydantic’s Philosophy: “Everything, Everywhere, All at Once”

Pydantic believes validation should happen at the model boundary. When you create a model instance, everything gets validated—types, formats, business rules, constraints. The model definition is the single source of truth.

# With Pydantic: ONE validation point
user = UserRegistration(**incoming_data)
# ↑ If this succeeds, ALL validation passed
# Types? ✓  Email format? ✓  Password rules? ✓  Age check? ✓

msgspec’s Philosophy: “Fast Types, You Handle the Rest”

msgspec believes in separating concerns:

Type validation: Lightning-fast, automatic, guaranteed, Just like Pydantic
Business validation: Your application, your rules, your code

# With msgspec: TWO validation layers
user = UserRegistration(**incoming_data)
# ↑ Types validated (str, int, etc.) - FAST
# ↓ Business rules - YOUR CODE
if len(user.password) < 8:
    raise ValueError("Password too short")

This felt wrong at first. Why split validation? Isn’t Pydantic’s approach more… complete?

But then I started to understand the advantages.

The Lightbulb Moment: Explicit Control

Here’s what changed my mind: msgspec gives you explicit control over when and how business validation happens.

Let me show you what I mean with a real example from my migration.

The Password Reset Problem

In my app, users can register with a password OR reset their password. Different endpoints, different validation needs:

With Pydantic, I had to do this:

class UserRegistration(BaseModel):
    email: EmailStr
    password: str
    full_name: str

    @field_validator('password')
    @classmethod
    def validate_password(cls, v: str) -> str:
        # Always enforces strong password
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        return v

class PasswordReset(BaseModel):
    email: EmailStr
    password: str
    reset_token: str

    @field_validator('password')
    @classmethod
    def validate_password(cls, v: str) -> str:
        # Duplicate validation code!
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        return v

Notice the duplication? I’m defining the same password validation in two places. If I change the rules (say, require special characters), I need to update both validators.

With msgspec, I could do this:

class UserRegistration(msgspec.Struct):
    email: str
    password: str
    full_name: str

class PasswordReset(msgspec.Struct):
    email: str
    password: str
    reset_token: str

# Validation logic lives in ONE place - the service
class UserService:
    @staticmethod
    def validate_password(password: str) -> None:
        """Centralized password validation"""
        if len(password) < 8:
            raise ValueError("Password must be at least 8 characters")
        if not any(c.isupper() for c in password):
            raise ValueError("Password must contain uppercase")
        if not any(c.isdigit() for c in password):
            raise ValueError("Password must contain number")

    async def register(self, data: UserRegistration):
        self.validate_password(data.password)  # Reusable!
        # ... create user

    async def reset_password(self, data: PasswordReset):
        self.validate_password(data.password)  # Same validation!
        # ... reset password

Suddenly it clicked: by separating type validation from business validation, msgspec lets me reuse validation logic across different contexts.

Wait, But msgspec Structs CAN Have Methods

Here’s where I had another revelation. I assumed msgspec Structs were just dumb data containers. They’re not!

class UserRegistration(msgspec.Struct):
    email: str
    password: str
    age: int

    def validate(self) -> None:
        """Custom validation - attached to the model!"""
        # Email validation
        if "@" not in self.email or "." not in self.email.split("@")[-1]:
            raise ValueError("Invalid email format")

        # Password validation
        if len(self.password) < 8:
            raise ValueError("Password must be at least 8 characters")
        if not any(c.isupper() for c in self.password):
            raise ValueError("Password needs uppercase letter")

        # Age validation
        if self.age < 18:
            raise ValueError("Must be 18 or older")

# Usage in controller
@post("/register")
async def register(data: UserRegistration) -> dict:
    # Types already validated by msgspec
    # Business validation is explicit
    data.validate()

    user = await create_user(msgspec.to_builtins(data))
    return {"message": "User created"}

So I could attach validation to the model, just like Pydantic. The difference? It’s explicit. I call .validate() when I decide it’s time.

This gives me control Pydantic doesn’t:

Validate at different points in the request lifecycle
Skip validation for trusted internal calls
Customize validation based on context
Separate validation errors from deserialization errors

The Performance Surprise

I hadn’t even been thinking about performance—I just wanted my validation to work. But then I ran some benchmarks.

import msgspec
import pydantic
import time

class PydanticUser(pydantic.BaseModel):
    id: int
    email: str
    full_name: str
    is_active: bool

class MsgspecUser(msgspec.Struct):
    id: int
    email: str
    full_name: str
    is_active: bool

data = {
    "id": 12345,
    "email": "user@example.com",
    "full_name": "John Doe",
    "is_active": True
}

# Benchmark Pydantic
start = time.perf_counter()
for _ in range(100_000):
    user = PydanticUser(**data)
pydantic_time = time.perf_counter() - start

# Benchmark msgspec
start = time.perf_counter()
for _ in range(100_000):
    user = msgspec.convert(data, type=MsgspecUser)
msgspec_time = time.perf_counter() - start

print(f"Pydantic: {pydantic_time:.3f}s")
print(f"msgspec:  {msgspec_time:.3f}s")
print(f"msgspec is {pydantic_time / msgspec_time:.1f}x faster")

# Output (Using: Ubuntu 24.04.3 LTS, Python 3.14.0b2):
# Pydantic: 0.053s
# msgspec:  0.017s
# msgspec is 3.2x faster

3.2x faster. For type validation alone.

I wasn’t even optimizing for performance, but suddenly my API endpoints felt snappier. Response times dropped. Under load, the difference would be even more noticeable.

Side by Side: The Complete Picture

Let me show you both approaches for the same real-world scenario—user registration with email, password, and age validation.

The Pydantic Way

from pydantic import BaseModel, EmailStr, field_validator

class UserRegistration(BaseModel):
    email: EmailStr
    password: str
    age: int
    full_name: str | None = None

    @field_validator('password')
    @classmethod
    def validate_password(cls, v: str) -> str:
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        if not any(c.isupper() for c in v):
            raise ValueError('Password must contain uppercase')
        if not any(c.isdigit() for c in v):
            raise ValueError('Password must contain number')
        return v

    @field_validator('age')
    @classmethod
    def validate_age(cls, v: int) -> int:
        if v < 18:
            raise ValueError('Must be 18 or older')
        if v > 120:
            raise ValueError('Invalid age')
        return v

# FastAPI endpoint
@app.post("/register")
async def register(data: UserRegistration):
    # Everything validated automatically
    user = await user_service.create(data.model_dump())
    return {"id": user.id}

Pros:

All validation in one place
Automatic on instantiation
EmailStr handles format validation
Clean endpoint code

Cons:

Validation logic tied to request model
Hard to reuse validators across models
Can’t skip validation for internal use
Slower serialization

The msgspec Way

import msgspec

class UserRegistration(msgspec.Struct):
    email: str
    password: str
    age: int
    full_name: str | None = None

    def validate(self) -> None:
        """Business validation - called when YOU want"""
        # Email validation
        if "@" not in self.email or "." not in self.email.split("@")[-1]:
            raise ValueError("Invalid email format")

        # Password validation
        if len(self.password) < 8:
            raise ValueError("Password must be at least 8 characters")
        if not any(c.isupper() for c in self.password):
            raise ValueError("Password must contain uppercase")
        if not any(c.isdigit() for c in self.password):
            raise ValueError("Password must contain number")

        # Age validation
        if self.age < 18:
            raise ValueError("Must be 18 or older")
        if self.age > 120:
            raise ValueError("Invalid age")

# Litestar endpoint
@post("/register")
async def register(data: UserRegistration) -> dict:
    # Types validated automatically by msgspec
    # Business validation is explicit
    data.validate()

    user = await user_service.create(msgspec.to_builtins(data))
    return {"id": user.id}

Pros:

Blazing fast type validation
Explicit validation control
Can reuse validation logic
Can skip validation when appropriate
Clear separation of concerns

Cons:

Must remember to call .validate()
No built-in EmailStr equivalent
More manual validation code
Endpoint code has one extra line

Alternative: Validation in Service Layer

With msgspec, you can also move validation to the service:

class UserRegistration(msgspec.Struct):
    email: str
    password: str
    age: int
    full_name: str | None = None

class UserService:
    async def create(self, data: dict) -> User:
        """Validate during creation"""
        # Email validation + uniqueness check
        if "@" not in data["email"]:
            raise ValueError("Invalid email")
        if await self.repository.email_exists(data["email"]):
            raise ValueError("Email already registered")

        # Password validation (reusable across endpoints!)
        self._validate_password(data["password"])

        # Age validation
        if data["age"] < 18:
            raise ValueError("Must be 18 or older")

        return await self.repository.create(data)

    @staticmethod
    def _validate_password(password: str) -> None:
        """Centralized password validation"""
        if len(password) < 8:
            raise ValueError("Password too short")
        # ... more checks

# Controller stays clean
@post("/register")
async def register(data: UserRegistration) -> dict:
    # Types validated by msgspec
    # Business rules validated in service
    user = await user_service.create(msgspec.to_builtins(data))
    return {"id": user.id}

This pattern centralizes business logic where it belongs—in the service layer, not the request model.

When to Use Which?

After living with both libraries, here’s my decision matrix:

Choose Pydantic When

You want automatic validation everywhere - Set it and forget it
You’re building a standard CRUD API - Pydantic’s patterns are well-established
Your team prefers “magic” - Less boilerplate, more automatic behavior
You need the ecosystem - Pydantic has integrations everywhere
Performance isn’t critical - Still fast enough for most use cases

Choose msgspec When

Performance matters - High-throughput APIs, real-time systems
You want explicit control - You decide when validation happens
You value separation of concerns - Business logic in services, not models
You’re using Litestar - Native integration, optimal performance
You need validation reuse - Share logic across different contexts

You Can Use Both

Here’s a secret: they can coexist. Use Pydantic for complex validation where you want the ecosystem, msgspec for high-performance paths.

# Pydantic for complex admin operations
class ComplexUserUpdate(BaseModel):
    # Use all of Pydantic's validation features
    ...

# msgspec for high-frequency endpoints
class UserListResponse(msgspec.Struct):
    # Fast serialization for list endpoints
    ...

What I Learned

This migration taught me that there’s no one “right” way to do validation. Pydantic and msgspec represent different trade-offs:

Pydantic says: “Validation should be automatic and comprehensive”
msgspec says: “Validation should be explicit and fast”

Both philosophies are valid. Both have their place.

I started this migration frustrated, thinking msgspec was incomplete. I ended it appreciating how explicit control over validation can actually make code clearer and more maintainable.

The .validate() call that felt like extra boilerplate? Now I see it as documentation—a clear signal that “validation happens here.” The manual validation methods? They’re reusable functions I can test independently.

And the performance? That was just a nice bonus I wasn’t even looking for.

The Migration Continues

My Litestar migration is still ongoing, but I’m no longer fighting msgspec. I’m embracing it. The initial confusion has given way to appreciation.

Would I go back to Pydantic for everything? No.

Would I use msgspec for everything? Also no.

The real lesson: understand your tools’ philosophies. Pydantic isn’t “complete” and msgspec isn’t “incomplete”—they’re just optimized for different values. Knowing when to use which makes you a better developer.

And sometimes, the libraries you think are missing features are actually giving you something more valuable: control.

(Written by Human, improved using AI where applicable.)