# Litestar Dataclasses

> Use Python dataclasses as Litestar transport models with explicit typing, defaults, and DTO interplay. Use when modeling request/response contracts with lightweight typed objects. Do not use when plugin-backed model systems (Pydantic/msgspec/attrs/ORM) are a better fit for the task.

- Skill: `alti3/litestar-dataclasses` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alti3/litestar-dataclasses`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alti3/litestar-dataclasses/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alti3 (https://skillmd.com/u/alti3)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alti3/litestar-dataclasses

---


# Dataclasses

## Execution Workflow

1. Define dataclasses for transport boundaries with explicit field types.
2. Use defaults and optionality intentionally to avoid ambiguous schemas.
3. Combine with DTO configuration when write/read shapes diverge.
4. Keep domain entities and transport dataclasses separate when needed.

## Implementation Rules

- Favor immutable or clearly controlled mutation patterns.
- Avoid embedding persistence/session behavior in dataclasses.
- Keep field names/schema stable for clients.
- Validate nested dataclass behavior in serialization paths.

## Example Pattern

```python
from dataclasses import dataclass
from litestar import post

@dataclass
class CreateUser:
    name: str
    email: str

@post("/users")
async def create_user(data: CreateUser) -> dict[str, str]:
    return {"email": data.email}
```

## Validation Checklist

- Confirm request binding maps correctly into dataclass fields.
- Confirm response serialization matches expected JSON schema.
- Confirm DTO include/exclude behavior remains predictable.

## Cross-Skill Handoffs

- Use `litestar-dto` for advanced shaping and nested field policy.
- Use `litestar-plugins` when switching to different model ecosystems.

## Litestar References

- https://docs.litestar.dev/latest/usage/dto/index.html