hex-restapi-schema
Use when a REST request or response body gains or changes a field — the pydantic models in `restapi/schemas/<resource>.py` (`FooResponse`, `FooListResponse`, `FooCreateRequest`, `FooUpdateRequest`), P
SKILL.mdplugins/pyhouse-hex/skills/hex-restapi-schema/SKILL.md
GitHubHex REST — API Schema
Produces one resource's schema module — the declared HTTP wire format for that resource, written here as pydantic models. The module is the boundary itself: domain entities never cross the wire, and schemas never cross into application or domain code.
When to use vs. neighbours
- Per-resource Pydantic schemas (request/response), including a field added to or removed from a body → this skill.
- The route that consumes these schemas and maps them field by field →
hex-restapi-endpoint. - The entity, value object, enum or filter record these models mirror — never imported here beyond enums →
hex-domain-model. - Cross-cutting
ErrorResponse/error_responses()inrestapi/schemas/errors.py→hex-restapi-app; which of those codes a route advertises →hex-restapi-endpoint. - The handlers beneath this delivery layer, and the command DTO carrying the same partial-update contract →
hex-application. - The container beneath this delivery layer →
hex-wiring. - The four schema names and any field name →
naming;__all__and the wildcard re-export intoschemas/__init__.py→python-packaging. - Asserting a response body in a test →
hex-test-restapi-endpoint.
Template — pydantic
File location
src/myapp/restapi/schemas/foos.py # the resource's schemas
src/myapp/restapi/schemas/__init__.py # update to re-export
The module holds several classes on purpose: one resource's request and response models are a closed set of declarations that change together, the case python-packaging lets share a module named for the set. A nested model used only by this resource's bodies lives in the same file.
Schema module
from collections.abc import Sequence
from typing import Annotated
from uuid import UUID
from pydantic import BaseModel, Field
__all__ = [
"FooCreateRequest",
"FooListResponse",
"FooResponse",
"FooUpdateRequest",
]
class FooResponse(BaseModel):
id: UUID
name: str
note: str | None
class FooListResponse(BaseModel):
items: Sequence[FooResponse]
total: int
limit: int
offset: int
class FooCreateRequest(BaseModel):
name: Annotated[str, Field(min_length=1)] # mirrors Foo's non-empty-name invariant
note: str | None = None
class FooUpdateRequest(BaseModel):
name: Annotated[str | None, Field(min_length=1)] = None
note: str | None = None
Absent and null both parse to None, which leaves the field unchanged (rule 6).
Other bindings
- msgspec
Struct, or attrs with a conversion layer. The declarations and the constraint spelling change — aMetaannotation or a validator argument instead ofField, an explicit decode step instead of model construction. Unchanged: the four names, the in-file order, the partial-update contract, the one-pagination-shape rule, and the ban on domain types crossing into the module. - A plain dataclass plus an explicit validation step. Honest only with the validation step actually written: something must reject a wrong shape before the handler sees it and must feed the published API document. A bare dataclass does neither, so rule 4 has nothing to attach to and the boundary stops being a boundary.
- Whatever the web framework parses bodies and generates its schema from. If the framework understands one model library only, that library is the binding: swapping it means supplying the parse-and-document step yourself, not renaming a base class.
Rules
Naming
- A CRUD resource's bodies take four names, and no other suffix (
namingfor the shared rules).
| Schema | Purpose |
|---|---|
FooResponse |
Single-entity GET / POST / PATCH response |
FooListResponse |
List GET response — items + the resource's pagination fields (offset: total/limit/offset; cursor: next_cursor/limit), matching hex-domain-model |
FooCreateRequest |
POST body |
FooUpdateRequest |
PATCH body — every field T | None = None |
Do not introduce alternate suffixes (Dto, Schema, In, Out). Another operation's body or response is Foo<Operation>Request / Foo<Operation>Response (naming's role suffixes) in the same module, and a nested object is its own model (rule 11).
Class form
- Each schema is a flat, self-contained declaration of one wire shape. No shared base carrying "common fields" across resources — repetition is intentional. The file must read top to bottom as the JSON a client will see, with no field inherited from out of frame.
- Order in the file:
Response,ListResponse,CreateRequest,UpdateRequest, then any nested model. Reads above writes; single above list.
Validation
- Only request schemas constrain their input, and the constraint is declared on the field (
python-style, Validation models). A response carries no constraint: its data already passed the domain's invariants. Every bound restates a limit the domain already has — an entity invariant, a value object's range, the width a field is persisted at. Restating it is intentional (schemas are wire contracts, and rejecting at the edge beats a 500 later); inventing it is not. A number with no domain behind it is a guess that will disagree with the domain the first time either moves. - A field constraint enforces input shape — length, range, pattern — never a business rule. The test: a constraint that has to read another field, another aggregate, or the clock is a business rule, and it belongs on an entity or a policy. Only what can be checked from the one value in front of you belongs here; no computed property or validator method encodes a rule either.
PATCH semantics
- Every field on
*UpdateRequestisT | None = None, andNoneis "leave unchanged". *CreateRequestlists required fields withoutNone, and gives a default only to an input that is genuinely optional. A create body with every field optional is an update body.
*ListResponse
*ListResponsecarries the resource's pagination shape — whichever one its filter record uses (hex-domain-model's one-pagination-shape rule for filter records picks exactly one), never a third:- offset paging →
items: Sequence[FooResponse],total: int,limit: int,offset: int. - cursor paging →
items: Sequence[FooResponse],next_cursor: str | None,limit: int. The routehex-restapi-endpointbuilds constructs whichever shape the filter uses, so the schema must match it (seehex-restapi-endpoint's cursor-list note). Don't mix the two.
- offset paging →
What never goes in a schema file
- No domain types beyond enums.
FooResponsedoes not import theFooentity, and a value object crosses as its primitive fields, mapped in the route. - No persistence concerns. Nothing that builds a schema straight from a stored row or mapped object — no ORM mode, no from-row constructor, no storage library's column types. A schema that can construct itself from the database has tied the wire format to the table, and the two then have to move together.
- No bare
dictorlistfield standing in for a nested object. A nested body is its own model in this file, declared and ordered like any other; adictfield publishes a hole in the wire contract that no generated document can describe.python-styleowns the declared-record rule.
Existing cross-cutting request schemas
- A request schema several resources share that already exists in its own module is reused, never re-declared per resource. None is presumed: most apps have none, so don't assume one exists.
Inlined typing / import rules
See python-style and python-packaging for the shared typing and import rules.
- Allowed:
pydantic, stdlib (uuid,collections.abc,datetime,decimal,typing), and domain enums only (FooCategory,Role). - Forbidden: domain entities, value objects and other dataclasses, repositories, application handlers, infrastructure types. Routers map field-by-field; the schema must not know about
Foothe entity. - No
from __future__ import annotations(python-style— the model library reads annotations at runtime). - No
Optional[...]—T | None(python-style).
Package wiring
After writing the module, update restapi/schemas/__init__.py:
from . import errors, foos
from .errors import *
from .foos import *
__all__ = errors.__all__ + foos.__all__
errors is hex-restapi-app's and stays; each resource module joins it in alphabetical order.
See python-packaging for package re-exports and __all__ composition.
Hard stops
- Asked to change
ErrorResponseorerror_responses()inrestapi/schemas/errors.py→ stop, usehex-restapi-app. - Asked to map a schema to a command, or a result to a schema → stop, use
hex-restapi-endpoint; the route maps field by field.