Input schema for path params

[ajiohjesse]

I'm using the OpenApiHandler with contracts. I have the following contract defined:

export const linksContract = {
  find: oc
    .route({
      path: "/links/{id}",
      method: "GET",
      description: "Get a short-link by id",
      tags: ["Links"],
    })
    .input(
      z.object({
        id: z.string(),
      })
    )
    .output(LinkSchema),
};

I'm getting the following error:

Some error occurred during OpenAPI generation: [OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: links.find When input structure is "compact", and path has dynamic params, input schema must be an object with all dynamic params as required.

Is there something I'm doing wrong?

[dosubot[bot]]

Hi @ajiohjesse! I'm Dosu and I’m helping the orpc team.

Your contract definition is correct—the error is actually a strict requirement enforced by the OpenApiHandler. When you use dynamic path params (like /links/{id}) and a "compact" input structure, your input schema must be an object with all dynamic params present and marked as required. This is necessary for accurate OpenAPI spec generation and was recently tightened in the codebase to avoid ambiguity and ensure all path params are explicitly required and typed [PR #814].

In your case, z.object({ id: z.string() }) is the correct schema, as long as id is required (which it is by default in Zod). If you’re still seeing the error, double-check that your schema isn’t accidentally allowing id to be optional or that there isn’t a mismatch between the path param and the schema property name. Also, make sure you’re using the latest version, as recent fixes improved handling of strict object schemas for dynamic params [PR #814].

If your schema matches the path params and all are required, OpenAPI generation should succeed. If you have additional properties in your schema, the generator now correctly separates them, so only the dynamic params need to be required [PR #814].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ajiohjesse]

@dosu I m on the latest version of orpc (1.8.5). The openapi generation is still failing.

Changing the find definition to

find: oc
    .route({
      path: "/links/{id}",
      method: "GET",
      description: "Get a short-link by id",
      tags: ["Links"],
      inputStructure: "detailed",
    })
    .input(
      z.object({
        params: LinkSchema.pick({ id: true }),
        query: z.object({}).optional(),
        body: z.object({}).optional(),
        headers: z.object({}).optional(),
      })
    )
    .output(LinkSchema),
    

now gives the following error:

Some error occurred during OpenAPI generation: [OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: links.find When input structure is "detailed", input schema must satisfy: { params?: Record, query?: Record, headers?: Record, body?: unknown }

[dosubot[bot]]

The error means the input schema for inputStructure: "detailed" must be a Zod object with only the keys params, query, headers, and body (all optional, but if present, must be object schemas—except body, which can be any type). For dynamic path params like /links/{id}, the params property must be a Zod object with all path params as required fields (not optional) and no extras.

Your current usage of LinkSchema.pick({ id: true }) for params will only work if id is required in LinkSchema. If id is optional in LinkSchema, or if LinkSchema contains other fields, this will cause OpenAPI generation to fail. The codebase and tests show the correct pattern is:

.input(
  z.object({
    params: z.object({ id: z.string() }),
    query: z.object({}).optional(),
    body: z.object({}).optional(),
    headers: z.object({}).optional(),
  })
)

Make sure params is exactly z.object({ id: z.string() }) and not a pick from a schema where id could be optional or there are extra fields. If you want to use LinkSchema, ensure it is strictly { id: string } for this route. If you use .pick({ id: true }), double-check that it produces a required-only schema for id and nothing else.

See the strict requirements and examples in the OpenAPI generator code and tests for reference.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ajiohjesse]

@dosu The id is not optional!

[dosubot[bot]]

Thanks for clarifying! If id is not optional, the most likely cause is that the OpenAPI generator is extremely strict about the structure of the input schema for routes with dynamic path params. For inputStructure: "detailed", the params property must be a Zod object with exactly the required path params as required fields—no extras, no optionals, and no additional properties. If LinkSchema includes any other fields (even optional ones), or if .pick({ id: true }) somehow retains metadata or extra keys, the generator will reject it.

The safest and most reliable pattern is to define params as z.object({ id: z.string() }) directly, not as a pick from a larger schema. This matches all the passing examples and tests in the codebase and avoids edge cases with .pick or schema inheritance. See the OpenAPI generator tests and docs for reference.

So, try this for your contract:

.input(
  z.object({
    params: z.object({ id: z.string() }),
    query: z.object({}).optional(),
    body: z.object({}).optional(),
    headers: z.object({}).optional(),
  })
)

If you need to reuse types, you can define a separate schema just for the path params. This should resolve the OpenAPI generation error.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[unnoq]

Make sure you configure ZodToJsonSchema correctly. There are two versions: one for v3 and one for v4.

[Chandraprakash-Darji]

I am facing same issue.

import z from "zod/v3";

import { ZodSmartCoercionPlugin, ZodToJsonSchemaConverter } from "@orpc/zod";

const handler = new OpenAPIHandler(router, {
  plugins: [
    new CORSPlugin({
      origin: env.API_ORIGIN || "http://localhost:3001",
      allowHeaders: ["Content-Type", "Authorization", "Cookie"],
      credentials: true,
      allowMethods: ["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
    }),
    new RequestHeadersPlugin(),
    new ZodSmartCoercionPlugin(),
  ],
  interceptors: [
    onError((error) => {
      logger.error("Request error:", error);
    }),
  ],
});

const openAPIGenerator = new OpenAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

getGroupById: base
    .route({
      description: "Retrieve a single lead group by id",
      method: "GET",
      path: "/{id}",
      inputStructure: "detailed",
    })
    .input(
      z.object({
        params: z.object({ id: z.string() }),
        query: z.object({}).optional(),
        body: z.object({}).optional(),
        headers: z.object({}).optional(),
      }),
    )
    .output(z.array(ContactSchema).nullable()),
    ```

[Chandraprakash-Darji]

sure

[Chandraprakash-Darji]

Issue is fixed, idk why but it needs the prefix somekind of, I have added v1 and it works

  find: base
    .route({
      summary: "Get lead group by id",
      description: "Retrieve a single lead group by id",
      method: "GET",
      inputStructure: "detailed",
      path: "/v1/:id",
    })
    .input(
      z.object({
        params: z.object({ id: z.string() }),
      }),
    )
    .output(z.array(ZBrandSchemas.ContactSchema).nullable()),
    ```
    
    

[unnoq]

path: "/{id}" should work, I try but it work as expected, please confirm you missing something or report bug. @Chandraprakash-Darji

[Chandraprakash-Darji]

I will create minimal repo and create an issue

[adileo]

I had the same issue I solved it by using

import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
const openAPIGenerator = new OpenAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

Probably the other version import { ZodToJsonSchemaConverter } from "@orpc/zod"; is not detecting the object as a valid zod object...