OpenAPI Compatible Parameter Serialization / Notation

[KingSora]

Describe the feature

Good day!

My usecase for orpc is to port an existing API and use it for end2end type safety and documentation. One of the biggest painpoints so far is that the bracket notation is not compatible with my current API and there is not really any alternative way of notating my path or query string which is compatible with the inputSchema.

OpenAPI offers many styles in which a string in a path or query can be serialized / deserialized.

One idea would be to introduce an additional inputNotation or inputStyle parameter in the Route interface:

oc.route({ method: 'GET', path: '/planets', inputNotation: 'pipeDelimited' })
.input(
  z.object({
    query: z.object({
      ids: z.array(z.coerce.number())
    }),
  }),
)

With the contract above an url like /planets?ids=1|2|3 would be valid. This could be done with all of the possible styles the openapi spec offers. The new inputNotation parameter could also be a complex object like inputNotation: { style: 'pipeDelimited', explode: false }.

In theory every query parameter could use its own notation, so it would also be desireable to make the notation configruable for each query parameter or path parameter separately. A possible API could look like:

oc.route({ method: 'GET', path: '/planets/{names}' })
.input(
  z.object({
    params: z.object({ 
       names: z.array(z.string())
    }),
    query: z.object({
      moons: z.array(z.string())
    }),
  }),
  // new parameter object which defines notations / styles
  {
     params: {
       names: { style: 'label' },
     },
     query: {
       moons: { style: 'matrix', explode: true },
     }
  }
)

Here the shape of the second parameter of the .input() function could be inferred from the passed standardSchema and the each field could be a inputNotation object which decides how string are interpreted.

Those are just thoughts of how to achieve the desired goal. oRPC could obviously also add its own notation here to make the whole thing backwards compatible, but I would suggest this feature to be someting for v2.

Additional information

• Would you be willing to help implement this feature?

Related: #1308 #518

[dinwwwh]

You can achieve inputNotation: 'pipeDelimited' in v1 with the code below. It's a bit complex and requires using this plugin if you are using the oRPC client: https://orpc.dev/docs/plugins/request-validation

import { os } from '@orpc/server'
import { z } from 'zod'

const ClientToServerIdsPipeDelimitedSchema = z.array(z.number()).transform(v => v.join('|'))
const ServerParsingIdsPipeDelimitedSchema = z.string().transform(v => v.split('|')).pipe(z.coerce.number())
const IdealIdsPipeDelimitedSchema = z.array(z.number())
const IdsPipeDelimitedSchema = ClientToServerIdsPipeDelimitedSchema.or(ServerParsingIdsPipeDelimitedSchema) as any as typeof IdealIdsPipeDelimitedSchema

const procedure = os
  .route({
    method: 'GET',
    path: '/planets',
    inputStructure: 'detailed',
    spec: current => ({
      ...current,
      parameters: current.parameters?.map((parameter: any) => {
        if (parameter.in !== 'query' || parameter.name !== 'ids') {
          return parameter
        }

        return {
          name: 'ids',
          in: 'query',
          required: true,
          style: 'pipeDelimited',
          explode: false,
        }
      }),
    }),
  })
  .input(z.object({
    query: z.object({
      ids: IdsPipeDelimitedSchema,
    }),
  }))

In v2, I am also working on this kind of issue. However, I don't think we can support all OpenAPI styles - particularly matrix, label, and simple - because they do not use ? and & for serialization, whereas the standard ?key=value&key2=value2 format is by far the most widely used and broadly supported approach for query parameters.

[KingSora]

@dinwwwh thanks for the codeexamples and the clarification :)

I believe there is a missunderstanding for the matrix, label, and simple styles. This table shows what combinations are allowed and the 3 styles are only allowed as path styles, not as query styles.

path allows: matrix, label, and simple.
query allows: form, spaceDelimited, pipeDelimited, deepObject.
header allows: simple
cookie allows: form, cookie

So lets make a full example with lets say label for path and pipeDelimited for query:

/color/.R=100.G=200.B=150?formats=rgb|hsl|cmyk

[dinwwwh]

@KingSora Thanks for the correction - so what styles do you need exactly, all of them?

[KingSora]

@dinwwwh I personally only need the pipeDelimited style that you showed me before, but I thought it might be worth to support all of them in v2.

[KingSora]

One small addition to this topic, there is also the attribute allowReserved for query parameters which decides whether reserved characters must be encoded. This might also be relevant for this feature.

[dinwwwh]

I’m currently implementing this. @KingSora, could you advise how we should handle cases where the value contains a delimiter character like |? Should this be treated as a limitation?

[KingSora]

@dinwwwh to be honest I'm not 100% sure of how to handle this... I've tried this OpenAPI Spec in the swagger editor

{
  "info": {
    "title": "My App",
    "version": "0.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "openapi": "3.1.1",
  "paths": {
    "/planets": {
      "get": {
        "operationId": "planet.list",
        "parameters": [
          {
            "name": "order",
            "in": "query",
            "required": true,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "string"
                }
              ]
            },
            "style": "pipeDelimited",
            "explode": false,
            "allowEmptyValue": true,
            "allowReserved": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {},
                    {
                      "not": {}
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

Entered a query param value string which contain the | character, swagger just percent escapes it in the final url, but I'm really not sure if thats the "correct" escaping strategy or whether there is even an escaping strategy in this case, because "pipeDelimited" urls are also valid if the pipes are percent escaped

Edit: AI tells me this:

Ah, the classic delimiter collision. It is incredibly frustrating when the character used to separate your data decides to show up inside your data.

Because OpenAPI (and HTTP in general) doesn't have a single, globally enforced rule for escaping characters inside custom-delimited strings like pipeDelimited, the solution depends entirely on how the backend server parses the incoming request.

Here are the standard ways to handle this, ordered from most likely to work to least.

1. URL Encode the Pipe (The "Fingers Crossed" Method)

The standard web approach is to URL-encode the literal pipe character inside your value into %7C.

Original Array: ["apple", "banana|split", "cherry"]

Query String: ?items=apple|banana%7Csplit|cherry

Why it might fail: This only works if the backend server splits the string by the | character before it decodes the URL. Many modern web frameworks (like Express, Spring, or Django) automatically URL-decode the entire query string before your application logic even sees it. If that happens, %7C turns back into | too early, and the backend incorrectly splits it into four items.
2. Backslash Escaping (The Custom Parser Method)

If the API developer anticipated this edge case, they likely implemented standard escape characters. You would put a backslash before the pipe: |.

Because backslashes and pipes both have special meanings in URLs, you should URL-encode both of them. \ becomes %5C and | becomes %7C.

Raw string intent: apple|banana\|split|cherry

Query String: ?items=apple|banana%5C%7Csplit|cherry

3. Change the OpenAPI Spec (If you control the API)

If you are the one building this API (or can yell at the person who is), the absolute best way to fix this is to stop using pipeDelimited arrays and use standard repeating query parameters instead.

In OpenAPI 3.x, you achieve this by setting the query parameter to style: form and explode: true.

OpenAPI YAML:
YAML

parameters:

• in: query
  name: items
  schema:
  type: array
  items:
  type: string
  style: form
  explode: true

Resulting Query String:
?items=apple&items=banana|split&items=cherry

By letting the & act as the array separator natively, your literal pipe character inside banana|split is completely safe and requires no special escaping (though URL encoding it to %7C is still best practice).
Summary: What should you do right now?

Try sending %7C in place of the pipe inside your value.

If the API returns an error or splits the value incorrectly, try %5C%7C (a URL-encoded \|).

If neither works, you will likely need to reach out to the API provider and ask them how their specific parser handles escaped delimiters, as they may have implemented a custom workaround (like || to represent a single pipe).

[dinwwwh]

@KingSora Thanks for your infos, Based on my research, I decided to treat these as limitations and not implement any special logic to handle these edge cases — because there is no universal way to deal with them. Adding such logic would only complicate things, given that OpenAPI in oRPC should support a wide range of clients and servers. If complex data is needed, json is the recommended solution.

[KingSora]

@dinwwwh I agree fully with you, thats the safest and easiest solution