# Litestar Custom Types

> Add custom type decoding/encoding and schema compatibility in Litestar for domain-specific values that are not handled by default serializers. Use when handlers need strongly typed custom inputs or outputs. Do not use when built-in scalar/model types already satisfy request and response contracts.

- Skill: `alti3/litestar-custom-types` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alti3/litestar-custom-types`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alti3/litestar-custom-types/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-custom-types

---


# Custom Types

## Execution Workflow

1. Define the domain type and its canonical wire representation.
2. Register type decoders/encoders at the appropriate layer.
3. Ensure OpenAPI schema generation remains accurate for custom values.
4. Add round-trip tests for decode, business usage, and encode output.

## Implementation Rules

- Keep serialization behavior stable and backward compatible.
- Fail fast with actionable error messages on invalid input.
- Avoid ambiguous representations that vary by locale/timezone.
- Keep custom type support centralized to prevent drift.

## Example Pattern

```python
from datetime import datetime
from litestar import Litestar, get


def parse_timestamp(value: str) -> datetime:
    return datetime.fromisoformat(value)

@get("/echo-ts/{value:str}")
async def echo_timestamp(value: datetime) -> dict[str, str]:
    return {"value": value.isoformat()}

app = Litestar(route_handlers=[echo_timestamp], type_decoders=[(datetime, parse_timestamp)])
```

## Validation Checklist

- Confirm valid payloads decode to the intended Python types.
- Confirm invalid payloads return deterministic client errors.
- Confirm encoded responses and generated schemas match actual runtime behavior.

## Cross-Skill Handoffs

- Use `litestar-openapi` if schema customization is substantial.
- Use `litestar-requests` and `litestar-responses` when custom types appear at API boundaries.

## Litestar References

- https://docs.litestar.dev/latest/usage/custom-types.html