Serialization

JSON encoding, custom serializers, schema export for AI agents.

Default JSON Serialization

EVOID returns dicts. The adapter handles JSON encoding:

@get("/menu")
async def list_menu() -> dict:
    return {"menu": MENU}  # Automatically serialized to JSON

What Happens Under the Hood

Serialization happens at two levels:

1. Pipeline level: Your handler returns a Python dict
2. Adapter level: The ASGI adapter converts dict → JSON response

# Your handler returns:
return {"menu": [{"name": "BLT", "price": 8.99}]}

# The adapter does:
import json
response_body = json.dumps({"menu": [{"name": "BLT", "price": 8.99}]})
# Sets Content-Type: application/json

The runtime doesn’t serialize. It passes your dict to the adapter. The adapter decides the format (JSON, msgpack, etc.).

Pydantic Models

Use Pydantic for structured serialization. Requires the pydantic extra:

uv add "evoid[pydantic]"

from pydantic import BaseModel
from datetime import datetime

class OrderResponse(BaseModel):
    id: int
    sandwich: str
    quantity: int
    total: float
    created_at: datetime = datetime.now()

@get("/orders/{order_id}")
async def get_order(order_id: int) -> dict:
    order = find_order(order_id)
    return OrderResponse(**order).model_dump()

Custom Serializers

For complex types, register a custom serializer:

from dataclasses import dataclass
from evoid.engines.serializer import set_serializer

@dataclass(frozen=True)
class Money:
    amount: float
    currency: str = "USD"

def serialize_money(obj):
    if isinstance(obj, Money):
        return {"amount": obj.amount, "currency": obj.currency}
    return None

set_serializer("money", serialize_money)

Schema Export

Export Intent schemas for documentation or AI agents:

from evoid import export_schemas, export_json_schemas

# Python objects
schemas = export_schemas()
for name, schema in schemas.items():
    print(f"{name}: level={schema.level}, fields={schema.metadata_fields}")

# JSON Schema (for OpenAPI, MCP, etc.)
json_schemas = export_json_schemas()
# {"create_order": {"type": "object", "properties": {...}}}

Debugging Serialization

When JSON encoding fails:

import json

@get("/debug")
async def debug_endpoint() -> dict:
    data = {"menu": MENU}
    try:
        json.dumps(data)
    except TypeError as e:
        print(f"Serialization error: {e}")
        # Fix: convert non-serializable types
    return data

What You Learned

Next: Shipping Online

Deploy Sandy’s online shop next: Shipping Online.