OpenAPI docs generate invalid request examples for oRPC endpoints

[hammadmajid]

I have this very basic Hono app as an example:

index.ts

import { Hono } from 'hono'
import { RPCHandler } from '@orpc/server/fetch'
import { onError } from '@orpc/server'
import { ZodToJsonSchemaConverter } from '@orpc/zod'
import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { os } from '@orpc/server'
import z from 'zod/v3'
import { ZodSmartCoercionPlugin } from '@orpc/zod'
import { CORSPlugin } from '@orpc/server/plugins'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'

const app = new Hono()

const ping = os.input(z.object({
  name: z.string()
})).output(z.object({
  message: z.string()
})).handler(async (context) => ({ message: `ping: ${context.input.name}` }))

const pong = os.input(z.object({
  name: z.string(),
  message: z.string()
})).output(z.object({
  response: z.string()
})).handler(async (context) => ({ response: `pong: ${context.input.name} - ${context.input.message}` }))


const router = {
  ping,
  pong,
  nested: { ping, pong }
}

const openAPIHandler = new OpenAPIHandler(router, {
  plugins: [
    new CORSPlugin(),
    new ZodSmartCoercionPlugin(),
    new OpenAPIReferencePlugin({
      schemaConverters: [new ZodToJsonSchemaConverter({

      })],
      specGenerateOptions: {
        info: {
          title: "ClassGuard API",
          version: "1.0.0",
        },

        servers: [
          { url: "http://localhost:8787/rpc", description: "Local API URL" },
        ],
      },
    })
  ],
})

app.get("/", async (c, next) => {
  const { matched, response } = await openAPIHandler.handle(c.req.raw, {
    context: {
      env: c.env,
    },
  })

  if (matched) {
    return c.newResponse(response.body, response)
  }

  await next()
})


const handler = new RPCHandler(router, {
  interceptors: [
    onError((error) => {
      console.error(error)
    }),
  ],
})

app.use('/rpc/*', async (c, next) => {
  const { matched, response } = await handler.handle(c.req.raw, {
    prefix: '/rpc',
    context: {} // Provide initial context if needed
  })

  if (matched) {
    return c.newResponse(response.body, response)
  }

  await next()
})

export default app

package.json

{
  "name": "server",
  "type": "module",
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy --minify",
    "cf-typegen": "wrangler types --env-interface CloudflareBindings"
  },
  "dependencies": {
    "@orpc/openapi": "^1.14.6",
    "@orpc/server": "^1.14.6",
    "@orpc/zod": "^1.14.6",
    "hono": "^4.12.25",
    "zod": "^4.4.3"
  },
  "devDependencies": {
    "@types/node": "^25.9.3",
    "wrangler": "^4.100.0"
  }
}

The problem

The generated Scalar (Swagger) documentation looks correct at first glance, as shown below:

However, the generated request examples do not actually work.

Running the cURL command shown by the documentation:

curl http://localhost:8787/rpc/ping \
        --request POST \
        --header 'Content-Type: application/json' \
        --data '{
    "name": "john"
  }'
{"json":{"defined":false,"code":"BAD_REQUEST","status":400,"message":"Input validation failed","data":{"issues":[{"code":"invalid_type","expected":"object","received":"undefined","path":[],"message":"Required"}]}}}⏎

but the request only succeeds when the payload is wrapped in a json property:

curl http://localhost:8787/rpc/ping \
              --request POST \
              --header 'Content-Type: application/json' \
              --data '{
      "json": { "name": "john" }
    }'

{"json":{"message":"ping: john"}}

Notice how the output is also wrapped in json key.

Questions

1. Why is the json wrapper required by default?
2. How can this behavior be disabled so that requests use the expected payload shape directly?
3. If the wrapper is required, how can the generated OpenAPI documentation be configured to accurately reflect the actual request and response formats?

[dosubot[bot]]

Hi @hammadmajid! I'm Dosu and I'm helping the unnoq's Org team.

The core issue here is a routing mismatch — your cURL requests are hitting /rpc/ping, which is handled by the RPCHandler (mounted at /rpc/*), not the OpenAPIHandler (mounted at /). These two handlers use fundamentally different protocols.

Why the json wrapper exists: The RPCHandler uses a custom serialization protocol that wraps payloads in {"json": {...}} to support rich JavaScript types that standard JSON can't handle (BigInt, Date, Set, Map, RegExp, etc.) [1]. It also includes optional meta for type reconstruction on the client side. This handler is designed exclusively for use with oRPC client-side libraries, not for manual HTTP calls [2].

How to fix it: The OpenAPIHandler accepts standard JSON without any wrapper. In your setup, you have it mounted at / but the RPCHandler at /rpc/*. When you curl http://localhost:8787/rpc/ping, that matches the RPCHandler route. To use standard JSON payloads, you should either:

1. Send requests to the OpenAPIHandler path instead — mount it at a dedicated prefix like /api and send requests to /api/ping:

app.all("/api/*", async (c, next) => {
  const { matched, response } = await openAPIHandler.handle(c.req.raw, {
    prefix: '/api',
    context: { env: c.env },
  })
  if (matched) return c.newResponse(response.body, response)
  await next()
})

Then curl http://localhost:8787/api/ping --data '{"name": "john"}' will work without any wrapper [3].

2. Keep using /rpc but with an oRPC client — if you're building a TypeScript frontend, use the @orpc/client package which handles the serialization automatically and gives you full type safety.

To answer your three questions directly:

1. The json wrapper is required by RPCHandler to enable rich type serialization beyond standard JSON [4].
2. It cannot be disabled on RPCHandler — use OpenAPIHandler instead for standard JSON format [5].
3. The OpenAPI documentation generated by OpenAPIReferencePlugin is accurate for the OpenAPIHandler — it shows the unwrapped format. The mismatch you're seeing is because you're sending those requests to the RPCHandler endpoint instead.

The idiomatic pattern is to run both handlers side by side: RPCHandler at /rpc for oRPC clients, and OpenAPIHandler at /api for standard REST calls [6].

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[dinwwwh]

{ url: "http://localhost:8787/rpc", description: "Local API URL" } -> { url: "http://localhost:8787/", description: "Local API URL" }

You are define incorrect server in openapi spec, you should point to OpenAPIHandler instead RPCHandler

[hammadmajid]

Without the /rpc prefix it throws 404 on all routes

[hammadmajid]

Fixed it by serving the endpoints with OpenAPIHandler instead of RPCHandler:

// remove this import
// import { RPCHandler } from '@orpc/server/fetch' 

app.use('/rpc/*', async (c, next) => {
  const { matched, response } = await openAPIHandler.handle(c.req.raw, {
    prefix: '/rpc',
    context: {}
  })

  if (matched) {
    return c.newResponse(response.body, response)
  }

  await next()
})

After switching to OpenAPIHandler, the endpoints accept the request body directly (without the json wrapper), and the generated OpenAPI/Scalar examples work as expected.

---

Credit to dinwwwh on Discord for pointing me in the right direction.