pre-alpha

Tutorial

2. Schemas

implemented Updated November 20, 2026 1 min read

A model describes a table; a Schema describes what crosses the API. A column reaches a client only when a schema names it.

# tracker/schemas.py
from typing import Annotated

from hinoki import Field, Schema, derive

from .models import Task


class TaskIn(Schema):
    """What a client may set. The owner is the caller, never a field."""

    title: Annotated[str, Field(min_length=1, max_length=120)]


@derive(Task, exclude=("owner_id",))
class TaskOut(Schema):
    """Every column of a task except its owner (derived from the model)."""
  • TaskIn is strict: no coercion, no unknown keys, and every problem is reported with its path. Validation runs in Rust before your code does.
  • TaskOut takes its fields from Task, with the model's types and limits. exclude=("owner_id",) keeps the owner out. Relations are never derived; you name them on purpose.
  • The owner is not a field of TaskIn, so a client cannot choose it. Server values passed to Task.acreate(data, owner_id=...) always win, and a schema never carries the primary key.

Schemas also support aliases, computed fields and tagged unions; see discriminated unions.

Recap

  • Input schemas list what a client may send, nothing more.
  • Output schemas can be derived from a model, minus what must stay private.
  • Ownership comes from the caller, never from the request body.

Next: 3. Operations.