Chat completion chunk object's `choices.delta.role` should be `string or null`

[ryeguard]

Description

ℹ️ This is an issue with the definition on the OpenAI Platform. I am filing it here in lack of a better place. Please point me elsewhere if this is not the right place. My suspicion is that this needs to be adressed in some upstream tool from OpenAPI and, e.g., Go SDK generation, i.e. Stainless which seems to be what OpenAI uses.

The OpenAI Platform docs state that the chat completions' choices.delta.role field is string. However, when making a request to OpenAI official endpoints (see example request/response below), the role is omitted for all except the first chunk. Hence, the role field should be string or null.

The OpenAPI spec for ChatCompletionStreamResponseDelta seems to be correct; there's no required array, so all fields are optional by OpenAPI convention.

This ambiguity has led to implementation issues in downstream SDKs (e.g., openai-go/v3 defines it as json:"role" without omitempty, causing spec violations). When re-marshaling chunks, this produces "role": "" instead of omitting the field, breaking spec compliance.

type ChatCompletionChunkChoiceDelta struct {
    Role string `json:"role"` // Missing omitempty due to unclear spec
}

Current OpenAPI schema

ChatCompletionStreamResponseDelta:
  type: object
  description: A chat completion delta generated by streamed model responses.
  properties:
    content:
      anyOf:
        - type: string
          description: The contents of the chunk message.
        - type: 'null'
    function_call:
      deprecated: true
      type: object
      description: >-
        Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be
        called, as generated by the model.
      properties:
        arguments:
          type: string
          description: >-
            The arguments to call the function with, as generated by the model in JSON format. Note that
            the model does not always generate valid JSON, and may hallucinate parameters not defined by
            your function schema. Validate the arguments in your code before calling your function.
        name:
          type: string
          description: The name of the function to call.
    tool_calls:
      type: array
      items:
        $ref: '#/components/schemas/ChatCompletionMessageToolCallChunk'
    role:
      type: string
      enum:
        - developer
        - system
        - user
        - assistant
        - tool
      description: The role of the author of this message.
    refusal:
      anyOf:
        - type: string
          description: The refusal message generated by the model.
        - type: 'null'

Example Request/Response to OpenAI

Request:

curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello"}],
    "stream": true,
    "max_tokens": 10
  }'

Response:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1763465300,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"xxx","choices":[{"index":0,"delta":{"role":"assistant","content":"","refusal":null},"logprobs":null,"finish_reason":null}],"obfuscation":"xxx"}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1763465300,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"xxx","choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}],"obfuscation":"xxx"}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1763465300,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"xxx","choices":[{"index":0,"delta":{"content":"!"},"logprobs":null,"finish_reason":null}],"obfuscation":"xxx"}

... 6 chunks ...

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1763465300,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"xxx","choices":[{"index":0,"delta":{"content":"?"},"logprobs":null,"finish_reason":null}],"obfuscation":"xxx"}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1763465300,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"xxx","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"obfuscation":"xxx"}

data: [DONE]