openai / openai/openai-openapi
OpenAI use of `type:` instead of `event:` in Server-Sent Event (SSE) framing as per the official WHATWG HTML Living Standard
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 2.5k
- Forks
- 527
- Avg merge
- 1h 46m
- Merged PRs (30d)
- 2
Description
Summary
While inspecting streamed responses from the OpenAI Responses API (using stream=true), I noticed that the Server-Sent Event (SSE) frames include a non-standard field name:
type: response.output_text.delta
data: {
"type": "response.output_text.delta",
...
}
According to the WHATWG HTML Living Standard, the valid field names in a text/event-stream response are:
event:,data:,id:, andretry:
Any other field names must be ignored by compliant clients.
Therefore, the type: field in the SSE framing is technically non-standard.
Expected (per SSE spec)
A compliant SSE stream that names an event type should use:
event: response.output_text.delta
data: { "type": "response.output_text.delta", ... }
This would allow spec-compliant clients (for example, the browser’s EventSource API) to listen for the event via:
source.addEventListener("response.output_text.delta", e => console.log(e.data));
Observed (OpenAI Responses API)
Instead of using the standard event: field, the stream uses:
type: response.output_text.delta
data: { "type": "response.output_text.delta", ... }
This framing works fine for custom clients or SDKs that parse the stream manually (e.g., using resp_stream_sse() in R or similar in Python/JS).
However, it’s non-compliant with the official SSE specification, meaning a spec-compliant EventSource client will ignore the type: field and treat all messages as default message events.
Questions / Clarification requested
- Is this divergence from the SSE standard intentional?
- Is there any internal or design reason OpenAI chose type: over event: in the framing?
- Would OpenAI consider aligning with the WHATWG standard by:
- adopting event: for framing, or
- documenting that the current
type:field is non-standard but intentionally supported only by OpenAI SDKs?
References
-
WHATWG HTML Living Standard – Server-sent events:
https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events -
MDN: Using Server-Sent Events:
https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events -
OpenAI Responses API (example stream):
Documentation link: https://platform.openai.com/docs/api-reference/responses
Why this matters
Adhering to the standard would make the Responses API compatible with native SSE clients (like browser EventSource and generic SSE libraries) without custom handling, improving transparency and interoperability for the community.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the Responses API definition and the linked WHATWG Server-sent events section first, then compare the documented stream framing with the EventSource example in the issue. Done means an explicit decision is recorded—either the framing uses event: for SSE event types or the non-standard type: behavior is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, networking
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100