Why does c.req.json() return any instead of unknown?

[darcyrush]

This is a genuine question, not a critique. Hono has been a delight to use and has already saved me days of work - but still curious;

By default await c.req.json() returns type any. I understand this aligns with JSON.parse() but I was always under the assumption JSON.parse() returning any instead of unknown was because unknown was added to the TypeScript language years after any and at that point due to backward compatibility it could never be changed. That was a very long time ago however.

Hono is a relatively recent framework. The focus on web-standards and being a micro-framework seems to align (intentionally or unintentionally) with the general JS ecosystem shift away from vulnerable, magical and bloated dependencies to more secure, explicit and thin dependencies. Alongside the security focused shift in libraries there is a parallel shift in TypeScript towards more and more strictly typed projects.

The theories of "Type Driven Design", "parse, don't validate" and "boundary validation" have been around for a while. The c.req.json() function I imagine is likely a very heavily used function and is is likely the boundary entry-point to many projects. Just seems odd to me that the entry-point of many projects disables typing.

I understand the function can take a generic (c.req.json<MyDto>()) but that is just type assertion which can be completely incorrect to the runtime value. Likewise I know there are some built in features like zod validation (c.req.valid()) but I'm talking about the situation where a developer may not want to use that and do their own validation for whatever reason.

Hono looks to be poised to be the framework of choice for modern TS projects wanting to move away from the supply-chain-attack mess currently unfolding, but this seems like a bit of a miss in relation to type safety so I wonder what I am missing or what the logic was for returning any in this particular case?

I know that code review, custom lint rules etc etc could work-around this, but that is still a workaround - educating junior developers is difficult enough without the argument of "if unknown is more accurate than any then why would a modern framework return any?"

I did stumble across this thread, but again, its a workaround and I don't see reasoning;
https://github.com/orgs/honojs/discussions/3331

[KippieG]

The short answer is: Hono deliberately mirrors the Web Platform's own Request.json(), which returns Promise<any>. Changing it to unknown would be a silent breaking change for every existing user calling .json() without an explicit generic — and it would also mean Hono is more opinionated than the platform it wraps.

Why the Web Platform returns any

The web-standard Request.json() is defined to return Promise<any>. This is not a TypeScript oversight; it reflects the reality that the runtime cannot know the shape at compile time, and the TypeScript DOM lib must match that. Hono's c.req.json() wraps that method, so inheriting any keeps the types consistent with what the underlying platform does.

Why Hono hasn't changed it unilaterally

If c.req.json() returned unknown, every codebase that currently does:

const body = await c.req.json()
const { name } = body  // ❌ error: 'name' does not exist on type 'unknown'

...would break with type errors. That's thousands of projects. The migration path (add explicit generics or narrow with type guards) is non-trivial, and it's forcing an opinion that the core library has so far left to the user.

The intended pattern

Hono's answer to "safe boundary entry" is the validator middleware, precisely because it gives you both runtime safety and inferred types:

import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const schema = z.object({ name: z.string(), age: z.number() })

app.post('/user', zValidator('json', schema), (c) => {
  const body = c.req.valid('json')  // typed as { name: string; age: number }
  // ...
})

c.req.valid('json') is genuinely typed — not a type assertion, because the middleware ran a runtime parse and Hono infers the result type from the schema. This is the design intent: the validator is the boundary.

If you want unknown right now

If your project avoids zod/valibot for whatever reason, you can enforce unknown at the call site with a thin wrapper:

async function parseJson(c: Context): Promise<unknown> {
  return c.req.json()
}

Or use the generic with a runtime type-guard, which at least makes the assertion explicit:

const body = await c.req.json<unknown>()
if (!isMyDto(body)) return c.json({ error: 'Invalid body' }, 400)

It is a fair critique that unknown would be the safer default for a modern framework. The linked discussion thread shows the Hono team is aware of the tension. But given the platform compatibility and migration cost, the current position is: use validators at the boundary rather than rely on the return type of .json() alone.