Support for conditional response types based on request body field (OpenResponses API pattern)

[tristanz]

Summary

I'm trying to implement the OpenResponses API specification using oRPC, but I've hit a limitation: the API uses a single endpoint that returns different response types based on a stream field in the request body.

The OpenResponses Pattern

The spec defines a single endpoint POST /responses where:

• stream: false (or absent) → Returns application/json with ResponseResource
• stream: true → Returns text/event-stream with SSE streaming events

OpenAPI Spec (from official spec)

{
  "paths": {
    "/responses": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateResponseBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseResource" }
              },
              "text/event-stream": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ResponseCreatedStreamingEvent" },
                    { "$ref": "#/components/schemas/ResponseCompletedStreamingEvent" }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

Full spec: https://github.com/openresponses/openresponses/blob/main/public/openapi/openapi.json

The Challenge with oRPC

oRPC's contract model assumes one procedure → one output type:

// This works for separate endpoints
const nonStreaming = oc
  .route({ method: 'POST', path: '/responses' })
  .input(CreateResponseBody)
  .output(ResponseResource)

const streaming = oc
  .route({ method: 'POST', path: '/responses/stream' })
  .input(CreateResponseBody)
  .output(eventIterator(StreamingEvent))

But I can't define a single procedure that:

1. Has one path (/responses)
2. Returns ResponseResource when input.stream === false
3. Returns AsyncIterator<StreamingEvent> when input.stream === true

Attempted Workarounds

1. Two procedures, same path - oRPC doesn't allow this (path conflict)
2. Union output type - Can't union a value type with an iterator
3. Custom handler logic - Loses type safety on the output

Proposed Solutions

Option A: Conditional output based on input field

const createResponse = oc
  .route({ method: 'POST', path: '/responses' })
  .input(CreateResponseBody)
  .output(ResponseResource, { when: (input) => !input.stream })
  .output(eventIterator(StreamingEvent), { when: (input) => input.stream })

Option B: Multiple media type outputs

const createResponse = oc
  .route({ method: 'POST', path: '/responses' })
  .input(CreateResponseBody)
  .output({
    'application/json': ResponseResource,
    'text/event-stream': eventIterator(StreamingEvent),
  })

Option C: Output type that can be either value or iterator

const createResponse = oc
  .route({ method: 'POST', path: '/responses' })
  .input(CreateResponseBody)
  .output(z.union([ResponseResource, eventIterator(StreamingEvent)]))

Context

This pattern is common in LLM APIs:

• OpenAI uses it for /chat/completions
• Anthropic uses it for /messages
• OpenResponses standardizes it

Being able to implement this pattern with oRPC would enable type-safe implementations of these popular API patterns.

Environment

• oRPC version: 1.4.3
• Target: Cloudflare Workers (fetch adapter)

[dosubot]

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

oRPC v1.4.3 doesn't natively support conditional response types or multiple media types for a single procedure—each route can only have one output schema, so you can't switch between a value and a stream based on an input field like stream source. Union output types that mix value and iterator aren't supported, and you can't define two procedures with the same path but different outputs source.

The fetch adapter for Cloudflare Workers automatically sets the Content-Type to application/json for value responses and text/event-stream for async iterator responses, but this is determined by the output type, not by request fields source.

Workarounds exist, but each has trade-offs:

• Custom handler logic: You can manually check input.stream and return either a value or an async iterator, but you lose type safety and OpenAPI spec accuracy.
• Plugins/interceptors: Some users extend the handler or use plugins to proxy raw Response objects or streaming bodies, but this requires custom code and careful handling to avoid double execution or loss of streaming source.
• Extending OpenAPIHandler: Advanced users have extended the handler to allow returning Response objects directly, which can preserve streaming and headers, but it's not officially supported and bypasses some oRPC features source.

There are active discussions and roadmap plans for supporting conditional outputs and multiple media types in future versions (possibly v2), with a proposed architectural change to decouple execution from transmission, allowing more flexible response handling source.

For now, the closest you can get is to use custom handler logic or plugins, but you'll need to accept some loss of type safety and spec fidelity. If you need strict OpenAPI compliance and type safety for this pattern, keep an eye on the v2 roadmap and related issues.

To reply, just mention @dosu.

---

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

   

[unnoq]

oRPC already partial support Option C, but limitations are built-in schema and spec generator:

const createResponse = os
  .route({ method: 'POST', path: '/responses' })
  .input(CreateResponseBody)
  .spec({
     // manually define output schema
   })
  .output(z.union([ResponseResource, 'DEFINE_YOUR_OWN_ZOD_SCHEMA_FOR_EVENT_ITERATOR']))
 .handler(async () => {
   
   if(stream) {
     return async function *(){
           // stream here 
     }()
   }
 
  return 'json' here
})