From afc7a5e9bb96d95224efc64ebf2f828ab3675183 Mon Sep 17 00:00:00 2001 From: Wadoud Date: Fri, 7 Aug 2026 16:35:16 +0100 Subject: [PATCH] docs(openapi): document OpenAPI path parameter syntax requirement ({id} vs :id) Add a `### Path parameter syntax ({id} vs :id)` section to `from-v1.mdx` with side-by-side v2 vs v1 CodeGroup examples, and a warning callout in `openapi/routing.mdx`. This clarifies that OpenAPI curly brace syntax (`/{id}`) is required in v2, while Express-style colon parameters (`/:id`) are treated as static literal paths. --- apps/content/docs/migrations/from-v1.mdx | 22 ++++++++++++++++++++++ apps/content/docs/openapi/routing.mdx | 4 ++++ 2 files changed, 26 insertions(+) diff --git a/apps/content/docs/migrations/from-v1.mdx b/apps/content/docs/migrations/from-v1.mdx index b30e7047b5..bb9796652c 100644 --- a/apps/content/docs/migrations/from-v1.mdx +++ b/apps/content/docs/migrations/from-v1.mdx @@ -105,6 +105,28 @@ const router = { +### Path parameter syntax (`/{id}` vs `/:id`) + +In v2, OpenAPI path parameters strictly require curly brace syntax (`/{id}`). Express-style colon parameters (`/:id`) are no longer converted automatically and are treated as literal static paths, causing path parameter parsing and input validation to fail. + + + +```ts v2 +import { openapi } from '@orpc/openapi' + +const getPlanet = os + .meta(openapi({ method: 'GET', path: '/planets/{id}' })) + .input(z.object({ id: z.string() })) +``` + +```ts v1 +const getPlanet = os + .route({ method: 'GET', path: '/planets/:id' }) + .input(z.object({ id: z.string() })) +``` + + + ## Procedure Builder ### `.callable` is no longer built in diff --git a/apps/content/docs/openapi/routing.mdx b/apps/content/docs/openapi/routing.mdx index 08eabead22..fd9a2dc15e 100644 --- a/apps/content/docs/openapi/routing.mdx +++ b/apps/content/docs/openapi/routing.mdx @@ -45,6 +45,10 @@ const getFile = os .input(z.object({ path: z.string() })) ``` +:::warning +Path parameters strictly require OpenAPI curly brace syntax (`/{name}`). Express-style colon parameters (`/:name`) are treated as literal static paths and will not extract path parameters into procedure input. +::: + :::info To customize path parameter encoding and decoding, see [Path Parameter Styles](/docs/openapi/input-and-output-mapping#path-parameter-styles). :::