Add OpenAPI 3.2 stream emission support with itemSchema

[Copilot]

Implementation Plan for Stream Support in OpenAPI 3.2

This PR implements support for streaming responses (including Server-Sent Events) in OpenAPI 3.2 emission and import using the itemSchema field.

Checklist

• 1. Add itemSchema support to OpenAPI 3.2 MediaType definition in types.ts
• 2. Create an SSE module (sse-module.ts) following the xml-module.ts pattern
• 3. Integrate SSE module into the OpenAPI emitter for emission support
• 4. Add package dependencies for @typespec/streams, @typespec/events, @typespec/sse
• 5. Use getStreamMetadata from @typespec/http/experimental to detect streams
• 6. Remove debug console.log statements
• 7. Tests passing for SSE emission
• 8. Handle @events decorator to emit proper SSE event structures
• 9. Handle @contentType decorator on union variants
• 10. Handle @terminalevent decorator (preserve with @extension)
• 11. Run formatter and linter
• 12. Add changelog entry with chronus
• 13. Generalize stream support for all content types

Changes Made

Type Definitions:

• Added itemSchema property to OpenAPIMediaType3_2 for streaming event schema definitions

SSE Module (sse-module.ts):

• Created stream detection and emission logic following xml-module.ts pattern
• Implements stream detection via @typespec/streams.getStreamOf
• Generates itemSchema with oneOf variants for @events union members
• Works with any stream content type (SSE, JSON Lines, etc.)

OpenAPI Emitter Integration:

• Integrated SSE module as optional dependency alongside XML/JSON Schema
• Modified getBodyContentEntry to detect all stream responses via getStreamMetadata
• Routes stream responses through emission path for OpenAPI 3.2 with itemSchema
• Generalized to support any HttpStream<ContentType, Type>, not just SSE streams

Testing:

• All stream tests passing
• Simplified test structure by removing namespaces and extra decorators
• Used ApiTester base for common libraries with stream-specific imports on top

Diagnostics:

• Added "streams-not-supported" diagnostic for OpenAPI 3.0/3.1
• Warning message indicates streams with itemSchema require OpenAPI 3.2.0

Stream Support

This implementation supports any stream type in OpenAPI 3.2.0:

• Server-Sent Events (SSE) with text/event-stream
• JSON Lines with application/jsonl
• Any custom HttpStream<ContentType, Type>

For OpenAPI 3.0/3.1, streams are emitted without itemSchema and a warning is generated.

• Fixes [Feat] OpenAPI - add support for SSE import and emission #8887

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feat] OpenAPI - add support for SSE import and emission</issue_title>
<issue_description>### Clear and concise description of the problem

Now that we have support for OpenAPI 3.2.0 (#8828 ) both in emissions and in importing descriptions to TypeSpec, it'd be nice to have support for importing SSE (server-sent events).
@timotheeguerin and I spent the better part of an hour combing through multiple specifications to understand what needs to happen here, so strap in, this is going to be a long issue.

Relevant resources

• Define streaming APIs(Server side events, log stream, etc.) #154 as the initial specification for sse in typespec
• [Feat] Add support for terminating events in streaming APIs OAI/OpenAPI-Specification#5096 ongoing discussion about terminal events
• https://github.com/Azure/azure-sdk-for-python/blob/894d166350f0ccbe2fae467e4093ed0c3b428213/sdk/ai/azure-ai-agents/azure/ai/agents/operations/_patch.py#L564 manual implementation of SSE for Azure AI Foundry: Agents threads run API
• https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/tests/assets/send_email_stream_response.txt an example of the payloads sent by this API
• WHATWG specification for SSE
• OAI 3.2.0 example on how to describe SSE
• OpenAI terminal event description
• OpenAI streaming responses documentation
• Blog post about using SSE APIs with OpenAI
• TypeSpec very sparse documentation for SSE

Import

Scenario 1 : no terminal event

Given the following OpenAPI Response object.

content:
  description: A request body to add a stream of typed data.
  required: true
  content:
    text/event-stream:
      itemSchema:
        type: object
        properties:
          event:
            type: string
          data:
            type: string
        required: [event]
        # Define event types and specific schemas for the corresponding data
        oneOf:
          - properties:
              event:
                const: userconnect
              data:
                contentMediaType: application/json
                contentSchema:
                  type: object
                  required: [username]
                  properties:
                    username:
                      type: string
          - properties:
              event:
                const: usermessage
              data:
                contentMediaType: application/json
                contentSchema:
                  type: object
                  required: [text]
                  properties:
                    text:
                      type: string

I'd expect aresulting TypeSpec description looking like this.

import "@typespec/streams";
import "@typespec/sse";
import "@typespec/events";

using SSE;

model UserConnect {
  username: string;
}
model UserMessage {
  text: string;
}

@TypeSpec.Events.events
union ChannelEvents {
  userconnect: UserConnect,
  usermessage: UserMessage,
}
op subscribeToChannel(): SSEStream<ChannelEvents>;

Note that the terminal event is NOT present, this is ok because it's an invention of some APIs, and is not part of the WHATWG spec. It should remain optional.

Here a couple of things are worth noting:

• imports for typespec streams/sse/events are added
• a using for SSE is added
• a @TypeSpec.Events.events decorator is added to the union type
• the return type of the operation is now SSEStream<ChannelEvents> (instead of ChannelEvents)
• The union type discriminator values are obtained by conventions based on the event properties in the schema (name is a convention)
• the union type member types are defined by convention by the schema of the data property, and the fact the content media type is application/json

Scenario 2: with terminal events

Given the following OpenAPI Response object.

content:
  description: A request body to add a stream of typed data.
  required: true
  content:
    text/event-stream:
      itemSchema:
        type: object
        properties:
          event:
            type: string
          data:
            type: string
        required: [event]
        # Define event types and specific schemas for the corresponding data
        oneOf:
          - properties:
              data:
                contentMediaType: text/plain
                const: "[done]"
                "x-ms-sse-terminal-event": true
          - properties:
              event:
                const: userconnect
              data:
                contentMediaType: app...

</details>

- Fixes microsoft/typespec#8887

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

[baywet]

@copilot cleanup the console logs you've added in this pull request

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - feature ✏️

adds support for emission and import of SSE for OpenAPI 3.2

[Copilot]

@copilot cleanup the console logs you've added in this pull request

Removed all debug console.log statements from openapi.ts and test files in commit 559641d.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[baywet]

leaving some comments after testing things locally

[baywet]

this is wrong, we shouldn't fallback on the main schema for streaming as schema is bounded and that does not work with streams which don't have collections bounds

[baywet]

this should be moved down to the condition when we detected a valid case

[baywet]

this is wrong, a streaming response could come from any operation that MAY return a response body