ADR-0011: Multi-status output schemas
- Status: Accepted
- Date: 2026-06-13
- Deciders: @VicenzoMF
Context
ADR-0003 made every route declare a single output Zod schema for the success body, and the runtime validates the handler's return value against it. ADR-0003 itself deferred the obvious next step — different shapes for different status codes — and named it explicitly:
Multiple output schemas keyed by status code. Deferred. v1 supports a single success-case schema. Multiple status-code schemas (e.g.,
200: User, 404: ErrorShape) is a likely follow-up ADR once we see real usage. […] Workaround for v1: a wide union output schema.
ADR-0008 (the unified error envelope) closed half the gap — every 4xx/5xx now has one declared shape (ErrorBody) built through c.error(...). But that shape is only enforced by the helper, never by a route's own contract:
Still a single success schema per route (ADR-0003); status-keyed response schemas (e.g.
404: ErrorBody) remain the deferred ADR-0003 follow-up.c.erroris not yet validated against a per-route error schema.
Two concrete costs of the single-schema model are visible in the examples today:
- Non-200 success bodies skip validation entirely.
examples/shop's checkout returnsc.json(order, 201)and carries this comment: "Returning a Response short-circuits the pipeline (skipping output validation) — the framework's only way to set a non-200 status." The 201 body is never checked againstOrderSchema. - The RPC client can't see error responses.
hc<typeof app>derives every response asstatus: 200(seerpc.ts). A client callingGET /users/:idhas no typed knowledge that a404with anErrorBodyis possible, so it cannot branch on it with type safety.
The forces: we want per-status contracts (typed and runtime-validated) without breaking the single-schema routes that already exist, without abandoning the "return a plain object or a Response" handler model, and while keeping the Hono RPC bridge (epic #11) honest so hc infers per-status responses.
Decision
We will let a route's output be either a single Zod schema (unchanged, ADR-0003) or a map from HTTP status code to Zod schema:
// Back-compat — the single-schema form is exactly ADR-0003.
output: UserSchema
// New — a status→schema map.
output: { 200: UserSchema, 404: ErrorBodySchema }type OutputMap = { readonly [status: number]: z.ZodTypeAny }
type OutputSpec = z.ZodTypeAny | OutputMapHow the handler signals the status
The handler's two existing return modes are preserved; the status is read from whichever one the handler uses, and the body is validated against the schema the map declares for that status:
| Handler returns | Status | Validated against |
|---|---|---|
a plain value (return user) | 200 | output[200] (or the single schema) |
c.json(body, status) (a Response) | status | output[status] if declared |
c.error(code, msg, { status }) (a Response) | status | output[status] if declared |
The model is deliberately small: a plain return is always the 200 body; every other status is set explicitly with c.json(body, status) or c.error(...). A map used with plain returns therefore declares 200; if it does not, the plain-return type is never and the handler must return a Response (e.g. a create route that only ever answers 201). We did not add magic to infer "the one 2xx" as the plain-status — explicit beats ambiguous, and it collapses the moment a route has two 2xx codes.
Validation semantics (composes with ADR-0009)
The output-validation mode (strict / log / off, ADR-0009) is unchanged and governs the consequence of a mismatch exactly as before. Multi-status only widens which schema a given response is checked against:
- Plain return → validated against the success schema (
output[200]for a map, or the single schema).strict500s on a mismatch,logserves the data and logs,offskips. This is byte-for-byte the ADR-0003/0009 behavior. Responsereturn, map form → if the response'sstatusis a declared key and the mode is notoff, Kata reads a clone of the body and validates it againstoutput[status]. On success the originalResponseis sent through verbatim (status, headers, and bytes untouched). On a mismatch the mode applies:strictreplaces it with the 500internal_output_shape_mismatchenvelope (ADR-0008);loglogs and still serves the original.Responsereturn, declared-status absent → passed through unvalidated. An undeclared status (e.g. a401produced by a middleware short-circuit, or a status the route simply didn't enumerate) is allowed and untyped, not an error.Responsereturn, single-schema form → passed through unvalidated. This preserves today's exact behavior (aResponsehas always short-circuited output validation) and keeps the single-schema form a zero-cost migration.- Non-JSON / unreadable
Responsebody → validation is skipped (Kata only validates JSON it can parse).
Plain returns are re-serialized from the parsed value (Zod transforms apply, as today); Response returns are validated as a shape check and forwarded unchanged — Kata never re-serializes a Response the handler already built, so it cannot silently drop a custom header or a transform the handler intended. This asymmetry is intentional and documented rather than papered over.
Declaring error statuses: ErrorBodySchema
Because c.error(...) always produces the ADR-0008 envelope, a route that wants its 404/409/422 typed and validated needs a schema that describes that envelope. Kata now ships one:
import { ErrorBodySchema } from '@katajs-framework/core'
output: { 200: UserSchema, 404: ErrorBodySchema }ErrorBodySchema (and the FieldIssueSchema it builds on) is the Zod mirror of the ErrorBody type from ADR-0008 — z.infer<typeof ErrorBodySchema> is assignable to ErrorBody. It is the canonical thing to put behind an error status; an app may substitute a stricter refinement (e.g. a literal error code) when it wants the tighter contract.
RPC typing (epic #11)
rpc.ts derives the Hono Schema from the modules tuple. For a single schema it still emits one endpoint with status: 200 (unchanged). For a map it emits a union of endpoints, one per declared status — exactly the shape Hono itself accumulates when a handler chains multiple c.json(body, status) calls. The client then narrows by status with Hono's own helper:
const res = await client.users[':id'].$get({ param: { id } })
if (res.status === 404) {
const { error } = await res.json() // ErrorBody — typed
return null
}
return res.json() // User — typed
// InferResponseType<…$get, 200> === User
// InferResponseType<…$get, 404> === ErrorBodyBreaking change
The value-level surface is backward compatible — a single output: Schema route compiles and behaves exactly as before. The type-level surface changes, which is why this is a breaking release:
Route's anddefineRoute's output generic widens fromO extends z.ZodTypeAnytoO extends OutputSpec.RouteHandlerReturn<O>is nowSuccessOutput<O> | Response(wasz.infer<O> | Response); for a single schemaSuccessOutput<O>isz.infer<O>, so the common case is unchanged.rpc.ts's derived endpoint type is a per-status union for map routes;InferResponseType<call>(no status argument) on a multi-status route is now a union of all status bodies. Code that assumed a bareInferResponseType<call>was the 200 body must pass the status:InferResponseType<call, 200>.
External code that parameterizes on these public types may need to adjust.
Alternatives considered
Alternative A — a single discriminated-union schema (status as a body field)
Keep one output schema, a z.discriminatedUnion('status', …). Rejected: the discriminant would be a body field, not the HTTP status line, so the wire status stays unmodeled and the RPC client still can't narrow on res.status. It also forces every response to carry a redundant status field. ADR-0003 already named the status-keyed map as the intended shape.
Alternative B — a tagged { status, body } return value
Require handlers to return { status: 404, body: … } instead of using c.json/c.error. Rejected: it discards the established "plain object orResponse" model and the c.error envelope ergonomics (ADR-0008), and is a far larger breaking change for callers than widening output.
Alternative C — validate every declared status, including middleware ones
Make the route responsible for declaring (and the runtime for validating) every status it can emit, including a 401 from an auth middleware. Rejected: a middleware short-circuit never passes through the handler-return path, so the route cannot intercept it; forcing the route to enumerate statuses its middleware chain produces couples the route to that chain. Undeclared statuses pass through untouched instead.
Alternative D — re-serialize Response bodies from the parsed data
On the Response path, rebuild the response from schema.parse(body) so Zod transforms apply uniformly with the plain path. Rejected as the default: it would drop any custom header the handler set and re-encode a body the handler already serialized. Validating as a shape check and forwarding the original is less surprising; transforms on non-200 bodies are rare. (An opt-in could revisit this.)
Alternative E — compile-time-check c.json(body, status) against output[status]
Tighten c.json so its body argument must match the schema declared for its status. Deferred: it requires threading the route's O into RouteContext (today parameterized only by registry + input). The declared map already types the client, and the runtime validates the server — v0.1 is covered. Additive follow-up if usage calls for it.
Consequences
Positive
- Per-status response contracts are both typed (RPC client narrows on
res.status) and runtime-validated, closing the two gaps above. - The
201/4xx"Response skips validation" hole is closed for any status a route declares — the shop checkout's workaround comment goes away. ErrorBodySchemagives error statuses a canonical, reusable schema, so the ADR-0008 envelope is now expressible in a route'soutputcontract.- Fully backward compatible at the value level: single-schema routes are untouched, so the migration is opt-in and incremental.
Negative / costs
- One more shape for
outputand a small new type surface (OutputSpec,OutputMap,SuccessOutput). Bounded and documented. - The
Response-path validation reads aclone()of the body (a buffering cost), but only in the map form, only for a declared status, and only when the mode is notoff— single-schema routes pay nothing new. - Plain-vs-
Responsevalidation is asymmetric (re-serialize vs shape-check). A deliberate trade documented above. - The single-schema form still does not validate
Responsereturns — by design, to keep back-compat. Teams wanting201bodies validated opt into the map form.
Follow-ups
- Teach a future
kata/output-status-maplint to flag a map that is used with plain returns but omits200(today the type already makes that anever). - Compile-time
c.json(body, status)↔output[status]checking (Alternative E). - Per-route output-validation mode (already an ADR-0009 follow-up) composes naturally with per-status schemas.
- Encourage
ErrorBodySchema(or a refinement) for 4xx/5xx map entries via the plannedkata/no-adhoc-error-shaperule (ADR-0008).
Companion rules
This ADR widens a type and runtime behavior; it introduces no new mandatory mechanical rule for v0.1. The existing kata/no-route-without-output-schema (ADR-0003) already enforces that output is present and is satisfied by the map form (it checks the key, not its shape). Rule IDs worth drafting later are listed under Follow-ups:
kata/output-status-map(future) — a status→schema map used with plain returns should declare a200entry.