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.

[DucMinhNe]

Short version: the any is a deliberate web-platform default, not an oversight — and you can already opt into unknown today without losing anything.

Why any is the default. Hono mirrors the platform Request/Response types. In lib.dom.d.ts (and the equivalent web types Hono builds on), Body.json() is typed json(): Promise<any>. Hono's signature is:

json<T = any>(): Promise<T>

So the default isn't "we chose any over unknown" so much as "the default type parameter matches what the web standard's .json() resolves to." Flipping the default to unknown would also be a breaking change for the very large number of existing call sites that do const body = await c.req.json() and then index into it — they'd all start erroring overnight. For a web-standards micro-framework, defaulting to the platform type and keeping it non-breaking is the consistent call.

You can get exactly the boundary you want — right now. Because it's json<T = any>(), you just pass unknown explicitly:

const body = await c.req.json<unknown>(); // Promise<unknown>
// now you're forced to validate/narrow before use — "parse, don't validate"

If you want this project-wide (so juniors can't accidentally get any), wrap it once:

const readJson = (c: Context) => c.req.json<unknown>();
// or a tiny middleware/helper your codebase uses everywhere

You can also enforce it at the lint layer with @typescript-eslint/no-unsafe-* rules, which will flag the any from a bare c.req.json() and push people toward the validated path.

And the first-class answer to "parse, don't validate" is the validator, which is genuinely parse-and-narrow (not an assertion like c.req.json<MyDto>()):

import { zValidator } from '@hono/zod-validator';
app.post('/', zValidator('json', schema), (c) => {
  const data = c.req.valid('json'); // fully typed AND runtime-checked
});

So the design intent is: default = platform-faithful and non-breaking (any), but the generic is the escape hatch — c.req.json<unknown>() gives you the strict boundary, and validator/c.req.valid() gives you real parse-don't-validate. You weren't missing anything; the unknown behavior is one type argument away.

[darcyrush]

I would prefer to hear from a maintainer rather than what appears to be curated LLM responses.

@usualoma @yusukebe apologies for directly pinging, but if either of you find time to give even a brief response it would be appreciated

[yusukebe]

Hi @darcyrush

Thank you for the thread, and sorry to be late. The reason is simple: as you said, JSON.parse() returns any, so I followed it. As you said, users can use c.req.json<MyDto>() to specify the type and c.req.valid() for validation.

I can understand the merit of returning unknown, and we have to consider it for the next major release.

Plus, actually, there was a policy for me before I created Hono that made it easy about types. This isn't told, but I wasn't super familiar with TypeScript when I started creating Hono. My thought about TypeScript types was that they can be "loose": the value could be any, and this was no problem. It's a historical reason.

But anyway, we have to accept modern things.

[darcyrush]

@yusukebe Thank you kindly for taking the time to give an honest response and glimpse into the history of hono! Your response allows me to give a truthful and accurate explanation to my colleagues.

I really hope returning unknown in those cases will be considered in future. I think hono would be an even easier sell in comparison to alternative frameworks if that was the case.

I understand it's not as simple as asking end users to add "as any" in a few places for older projects, but given the ecosystem today, I'm also curious how difficult such a change would actually be. Regardless, thank you to everyone involved in the project so far.