ADR-0024: Non-JSON output contracts (raw()) and a unified Response validation path
- Status: Accepted
- Date: 2026-08-18
- Deciders: @VicenzoMF
Context
ADR-0003 makes output mandatory and Kata sells it as "responses are validated at runtime (500 on mismatch) and hc<typeof app> infers return types from it." That promise never held for a route that returns a Response directly — the only way to serve a non-JSON body:
| declaration | handler returns | result |
|---|---|---|
output: z.string() | the string | content-type: application/json — CSV delivered as a JSON string literal |
output: z.string() | new Response(csv, {headers}) | correct text/csv — the only thing that worked |
output: z.number() (a flat lie) | the same Response | 200, identical correct CSV. verify clean, tsc clean, runtime silent |
Two bugs produced this, in two different code paths:
- Single-schema form.
buildResponsetreated anyResponsereturn as an unconditional short-circuit:!isZodSchema(output)isfalsefor a single schema, so validation was skipped entirely. This was even documented as a feature ("a custom header or content type the handler set is preserved"). - Map form (ADR-0011).
validateResponseBodytried, viaresponse.clone().json(), and on a non-JSON body silently returned the response unchanged — so a CSV was unvalidatable in both forms, and the two forms disagreed about whether aResponsewas checked at all.
rpc.ts compounded this: outputFormat was hardcoded to 'json', so hc<typeof app> always typed an endpoint as JSON. A typed client calling a non-JSON route called .json() on a text/csv body and threw. RouteHandlerReturn<O> = SuccessOutput<O> | Response was the only place the escape hatch was documented — a type alias, not the README or guide.
A mandatory field that cannot be wrong is worse than an optional one: it reads as a guarantee.
Decision
1. raw() — a declared non-JSON contract
output grows a second kind of entry alongside a plain Zod schema:
export type RawOutput<T extends z.ZodTypeAny = z.ZodTypeAny> = {
readonly __kata: 'raw'
readonly contentType: string
readonly schema: T
}
export function raw<T extends z.ZodTypeAny>(contentType: string, schema: T): RawOutput<T>
export type OutputEntry = z.ZodTypeAny | RawOutput
export type OutputMap = { readonly [status: number]: OutputEntry }
export type OutputSpec = OutputEntry | OutputMapraw('text/csv', z.string()) declares the response's content-type and a schema for its text body (not JSON). It slots in anywhere an entry was accepted before — the single-entry shorthand or a status key in the map:
output: raw('text/csv', z.string()) // single entry
output: { 200: raw('text/csv', z.string()), 404: ErrorBodySchema } // map2. The escape hatch becomes declared, not implicit, at the type level
RouteHandlerReturn<O> now derives what a handler may return from what O actually is:
export type RouteHandlerReturn<O extends OutputSpec> = O extends RawOutput
? Response
: O extends z.ZodTypeAny
? SuccessOutput<O>
: SuccessOutput<O> | ResponseOis a singleraw()entry → only aResponsesatisfies it (no plain-value equivalent exists).Ois a single plain Zod schema → only the plain value satisfies it. A bareResponseis now atscerror — this is the change that closes the hole, and it is deliberately narrower than "forbidResponseeverywhere": see Alternative B for why a blanket ban was rejected.Ois a map → unchanged from ADR-0011 (SuccessOutput<O> | Response): a plain value for a declared200, or aResponsefor any status, declared or not. This is still howc.error/c.json(body, status)work, and still how an undeclared status (a401from an auth middleware, a redirect) passes through.
3. Unify single-entry and map validation of a Response
Both forms are now read through one lookup that treats a single entry as sugar for { 200: entry }:
function entryForStatus(output: OutputSpec, status: number): OutputEntry | undefined {
if (isOutputEntry(output)) return status === SUCCESS_STATUS ? output : undefined
return output[status]
}buildResponse calls this for every Response return, regardless of form. A declared status is validated — as JSON (validateResponseBody, unchanged shape check from ADR-0011) or, for a raw entry, as text against its content-type + schema (validateRawResponseBody, new). An undeclared status passes through unvalidated, exactly as ADR-0011 already allowed.
This closes the original bug directly: output: z.string() is now { 200: z.string() } for lookup purposes, so a Response returned at its default status (200) — exactly the CSV exploit — is validated as JSON, fails (CSV text is not valid JSON), and 500s in strict. To serve real CSV, the route must declare raw('text/csv', z.string()), which the type system now also requires the handler to honour.
4. raw() validation: content-type always, body only in strict
declared status? → no → pass through unvalidated
│ yes
content-type matches (params ignored)? → no → strict: 500 / log: log + pass through
│ yes
mode === 'strict'? → no → pass through (body never read)
│ yes
clone().text() matches schema? → no → 500
│ yes
pass throughContent-type comparison is a header read — cheap, so it runs whenever the mode is not off. Body comparison needs response.clone().text(), which buffers the whole response into memory; that cost is paid only in strict. A route serving a large download must never pay it in log (the production default) — Kata will never silently buffer a stream-backed response outside strict. Because that means the body genuinely goes unchecked in log (content-type still is) — and neither goes checked at all in off, an explicit, documented full opt-out (ADR-0009) that needs no per-route reminder — registerRoute logs one logger.warn per route at startup (not per request) specifically when the resolved mode is log and the route declares a raw() entry, so that one real gap is visible instead of silent.
5. Fix the RPC bridge
outputFormat is derived per entry instead of hardcoded:
type MapEntryEndpoint<I, E, S extends number> = E extends RawOutput<infer T extends z.ZodTypeAny>
? HonoEndpoint<I, z.infer<T>, S, 'text'>
: E extends z.ZodTypeAny
? HonoEndpoint<I, z.infer<E>, S, 'json'>
: neverhc<typeof app> now types a raw() endpoint's client response with .text(): Promise<T> and .json(): Promise<never> — calling .json() on a CSV endpoint is a compile error, not a runtime SyntaxError.
6. Documentation
docs/guide/routes-schemas.md gets a "Non-JSON responses: raw()" section and a rewritten "Validating a Response" section describing the unified lookup; packages/kata/README.md gets a short mention. No more "output is unenforced for Response returns" caveat — the caveat is fixed, not just documented.
A structural-typing caveat (known, accepted)
TypeScript is structural: Response (the DOM type) has real properties named ok, status, statusText, headers, body, bodyUsed, redirected, type, url. If a plain output schema's shape happens to be a subset of those — e.g. z.object({ ok: z.boolean() }) — a Response value is structurally assignable to it, and RouteHandlerReturn's new restriction does not catch it at the type level. This is a narrow, coincidental gap inherent to structural typing, not a flaw in the mechanism: it requires a schema whose field names and types happen to alias Response's own shape, which is unlikely by accident for a real domain object. It is called out here rather than left for someone to discover; no mitigation is proposed (a nominal brand on Response is not something Kata controls).
{ ok: boolean } is exactly this shape, and it is a common convenience placeholder — this codebase's own tests use it repeatedly. When a Response slips through this gap at status 200, entryForStatus's unify (point 3) treats that status as declared and runtime-validates it as JSON, which means a clone().json() read same as any other declared status. If that Response's body is a slow or intentionally-stalled stream — as one context.test.ts fixture for the ADR-0020/issue #207 header-merge rebuild path turned out to be — that read hangs the request until the body resolves, not just "validates nothing." This is not a new hazard: validateResponseBody's clone().json() already carried it for any map-form route with a declared status (ADR-0011). ADR-0024 widens when it can trigger (a single-schema route's own 200, via the structural gap above) but does not introduce the underlying risk, and fixing clone().json() against a hostile/slow body in general is a pre-existing, orthogonal robustness gap this ADR does not take on. The one fixture that hit it was updated to set outputValidation: 'off', since it tests header merging, not output validation.
Alternatives considered
Alternative A — validate a JSON schema against clone().text() too (no raw())
Skip the new declaration; just make the existing schema's safeParse run against whatever the body actually is (JSON-parsed if possible, else raw text). Rejected: this reintroduces exactly the "z.number() passes for a CSV body" bug, since any schema — right or wrong — would validate something. raw() makes the intent (and the content-type) an explicit, checkable declaration instead of inferring it from what happened to parse.
Alternative B — forbid a bare Response for every output form, including maps
The blanket version of point 2: no output declaration, single or map, ever allows a bare Response unless every status is enumerated. Rejected: it would break the established, tested, and ADR-0011-sanctioned pattern of a map declaring only its 200/success schema and letting c.error/an auth middleware answer undeclared statuses untyped ({ 200: OrderSchema } + a 401 from requireAuth that the route never sees or declares). That pattern is real and used throughout the examples; forbidding it is a much larger, unjustified breaking change than the bug being fixed calls for.
Alternative C — a kata verify rule for the cases the type system cannot see
The original sketch for this issue proposed a static rule flagging a raw() entry whose handler can't be proven to return a Response (untyped/loosely-typed code, as any escapes). Deferred, not shipped: RouteHandlerReturn already makes this a hard tsc error for all typed code reached through the public defineRoute API, and the general "an as never/boundary cast needs a kata-allow: hono-boundary comment" convention (kata/no-raw-boundary-cast) already covers the escape-hatch case. A dedicated rule is listed under Follow-ups rather than built speculatively.
Alternative D — re-derive the escape hatch per status instead of per declaration
Let the type system infer, per possible response, whether a Response is legal based on the runtime status value the handler is about to use. Rejected as infeasible: TypeScript cannot see a Response's runtime status at the type level (new Response(x, { status: 200 }) and new Response(x, { status: 404 }) are the same type). The declaration (single entry vs. map, which statuses a map lists) is the only thing the type system can actually key off; Alternative B and the chosen design both work within that constraint.
Consequences
Positive
- A route can serve a real non-JSON body — CSV, plain text, a download — with a declared, validated, RPC-typed contract instead of an undocumented escape hatch.
- The original bug (a wrong-typed schema silently "validating" a
Response's body) is closed for the case it was reported in: a plain schema's own status. - Single-entry and map forms agree on whether and how a
Responseis checked — one lookup, one mental model, instead of two undocumented behaviours. hc<typeof app>cannot silently mistype a non-JSON endpoint as JSON anymore.- Never buffers a stream-backed response outside
strict— the buffering cost ADR-0011 already accepted for JSONResponsevalidation is not widened to non-JSON bodies in production.
Negative / costs
- Breaking, deliberately. A single-entry route (
output: SomeSchema) that returnedc.error(...)/c.json(body, otherStatus)for a second status no longer compiles; it must move to the map form (output: { 200: SomeSchema, 404: ErrorBodySchema }) — the same migration ADR-0011 already established for routes that want a non-200 body validated. Three example routes (examples/shop'sgetOrderRoute/getProductRoute/addCartItemRoute) and thekata initscaffold'sgetGreetingRouteneeded exactly this migration; severalpackages/kataunit tests using a placeholder{ ok: z.boolean() }schema were migrated too, for clarity, even though the structural-typing caveat above meant a few of them still happened to compile unchanged. - Rebasing onto
mainsurfaced a second, independent confirmation of the bug this ADR fixes: issue #207's ownexamples/hello's/export.csvroute (diag.route.ts) declared a plainoutput: ExportCsvOutputSchemaand returned a raw CSVResponsedirectly — the schema's own doc comment said, in so many words, "output validation never actually runs against this schema." Migrated toraw('text/csv', ExportCsvOutputSchema), which is now genuinely checked. The rebase also surfaced one runtime interaction worth naming explicitly: acontext.test.tsfixture for the ADR-0020/#207 header-merge rebuild path returns aResponsewith a deliberately-stalled stream body againstoutput: z.object({ ok: z.boolean() })(the structural gap above) — under the unify (point 3), that made the stream getclone()d for JSON validation and hang the test. Fixed by settingoutputValidation: 'off'on that fixture, since it tests header merging, not output validation; see the caveat section for why this is a pre-existing risk (ADR-0011) that ADR-0024 widens rather than introduces. raw()'s body validation isstrict-only, so a production (log-mode) route gets no runtime guarantee that its non-JSON body matches its declared schema — only its content-type. Mitigated by the startup warning and bystrictstill being the dev/CI default, matching ADR-0009's own strict/log split.- The structural-typing caveat above is a real, if narrow, gap the type system cannot close.
- One more branch in the runtime response-building pipeline (
entryForStatus,validateRawResponseBody,mediaType). Bounded and unit-tested.
Follow-ups
kata/raw-output-requires-response(or similar) — the deferredkata verifyrule from Alternative C, for handlers the type system cannot check.- A structured metric/log channel for the startup "body unchecked outside strict" warning, mirroring the ADR-0009 follow-up for output-mismatch logging.
- Per-route
outputValidationoverride (already an ADR-0009 follow-up) would let a specificraw()route opt into strict body-checking even under an app-widelogmode, without paying the buffering cost everywhere else. docs/pt/guide/routes-schemas.md(the Portuguese translation) still describes the pre-ADR-0024 behaviour and needs syncing.
Companion rules
This ADR changes runtime behavior and a public type signature; it introduces no mandatory mechanical lint rule for v1 — the type system is the primary enforcement mechanism (RouteHandlerReturn), same posture ADR-0009 took for its own runtime-only change. The rule worth drafting later is listed under Follow-ups:
kata/raw-output-requires-response(future) — flag araw()output entry whose handler cannot be statically proven to return aResponse.
Note on numbering
Drafted 2026-08-18 as a repo-root ADR-0022-draft.md awaiting placement into docs/adr/; the decision shipped in code (PR #223, issue #208) before the draft was committed. By the time it was rediscovered (issue #261), the 0022 slot had already been taken by ADR-0022 (docs-MCP lexical search). This file is that draft, otherwise unchanged, filed under the next free number, 0024.