markstuart-oai · Oct 30, 2026 · Oct 30, 2026
@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: c7d28dc2-cc3d-47a3-9b98-f74f327d7d06
-openapi_spec_hash: c735bf35306196d3be264afacd380ef5
-openapi_transformed_spec_hash: 26fd6dfec1625525dae954f7de5f80c1
-config_hash: 4e0613192a6ffb1791a25180a99a769c
-codegen_sha: 8a8a0ff64e79040ac5f29532ff061bdfa567764a
-codegen_hash: b296d6e5af2a21ef64ed15e9b4984854ca700063db8490798bd25ebbf58e3b34
+generation_id: dfd43ede-47aa-4010-85a7-902500e246d3
+openapi_spec_hash: d57efec7c76a156447c9ab739b446dc1
+openapi_transformed_spec_hash: 834e733aeb5425eae15cc1643c7e67cb
+config_hash: 1d0b20f04f1b5fe5edc8b60dbad7a7d9
+codegen_sha: 95b1337ab8409a20ab2d5e3ce321bdb23ec6c18c
+codegen_hash: 51771b70d1cefb3ce7562a0b0857a64d6585b338458d3b8de951b8e40c6c5391
@@ -299,23 +299,20 @@ private constructor(
         ) : this(content, role, id, type, mutableMapOf())
 
         /**
-         * The text input to the model.
+         * The required content of a message item. Tool call and output items omit content.
          *
-         * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
-         *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
+         * Use `_content().isMissing()` to check for content before reading it.
+         *
+         * @throws OpenAIInvalidDataException if content is missing, null, or has an unexpected
+         *   type. Tool call and output items normally omit content.
          */
         fun content(): Content = content.getRequired("content")
 
         /**
-         * The message role. Always `user`.
-         *
-         * Expected to always return the following:
-         * ```java
-         * JsonValue.from("user")
-         * ```
+         * The role on a message item, defaulting to user. Tool call and output items omit role.
          *
-         * However, this method can be useful for debugging and logging (e.g. if the server
-         * responded with an unexpected value).
+         * Returns the raw role. Use `_role().isMissing()` to check its presence; tool call and
+         * output items omit this field.
          */
         @JsonProperty("role") @ExcludeMissing fun _role(): JsonValue = role
 
@@ -328,6 +325,9 @@ private constructor(
         fun id(): Optional<String> = id.getOptional("id")
 
         /**
+         * The item type. An omitted type denotes a message. Tool call and output items have their
+         * corresponding tool type.
+         *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
          */
@@ -421,7 +421,7 @@ private constructor(
                 additionalProperties = item.additionalProperties.toMutableMap()
             }
 
-            /** The text input to the model. */
+            /** The required content of a message item. Tool call and output items omit content. */
             fun content(content: Content) = content(JsonField.of(content))
 
             /**
@@ -479,6 +479,10 @@ private constructor(
              */
             fun id(id: JsonField<String>) = apply { this.id = id }
 
+            /**
+             * The item type. An omitted type denotes a message. Tool call and output items have
+             * their corresponding tool type.
+             */
             fun type(type: Type) = type(JsonField.of(type))
 
             /**
@@ -547,14 +551,21 @@ private constructor(
                 return@apply
             }
 
-            content().validate()
-            _role().let {
-                if (it != JsonValue.from("user")) {
-                    throw OpenAIInvalidDataException("'role' is invalid, received $it")
+            if (_type().isNull()) {
+                // The released Item validated null like an omitted type. Preserve its
+                // field checks without changing the wire value or newer item variants.
+                content().validate()
+                _role().let {
+                    if (it != JsonValue.from("user")) {
+                        throw OpenAIInvalidDataException("'role' is invalid, received $it")
+                    }
                 }
+                id()
+                type().ifPresent { it.validate() }
+            } else {
+                val properties = _allProperties()
+                com.openai.models.live.DecisionInputItemValidation.validate(properties)
             }
-            id()
-            type().ifPresent { it.validate() }
             validated = true
         }
 
@@ -579,7 +590,7 @@ private constructor(
                 (if (id.asKnown().isPresent) 1 else 0) +
                 (type.asKnown().getOrNull()?.validity() ?: 0)
 
-        /** The text input to the model. */
+        /** The required content of a message item. Tool call and output items omit content. */
         @JsonDeserialize(using = Content.Deserializer::class)
         @JsonSerialize(using = Content.Serializer::class)
         class Content
@@ -1790,6 +1801,10 @@ private constructor(
             }
         }
 
+        /**
+         * The item type. An omitted type denotes a message. Tool call and output items have their
+         * corresponding tool type.
+         */
         class Type @JsonCreator private constructor(private val value: JsonField<String>) : Enum {
 
             /**

@@ -340,27 +340,27 @@ private constructor(
         fun id(): String = id.getRequired("id")
 
         /**
-         * The text input to the model.
+         * The required content of a message item. Tool call and output items omit content.
          *
-         * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
-         *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
+         * Use `_content().isMissing()` to check for content before reading it.
+         *
+         * @throws OpenAIInvalidDataException if content is missing, null, or has an unexpected
+         *   type. Tool call and output items normally omit content.
          */
         fun content(): Content = content.getRequired("content")
 
         /**
-         * The message role. Always `user`.
+         * The role on a message item. Tool call and output items omit role.
          *
-         * Expected to always return the following:
-         * ```java
-         * JsonValue.from("user")
-         * ```
-         *
-         * However, this method can be useful for debugging and logging (e.g. if the server
-         * responded with an unexpected value).
+         * Returns the raw role. Use `_role().isMissing()` to check its presence; tool call and
+         * output items omit this field.
          */
         @JsonProperty("role") @ExcludeMissing fun _role(): JsonValue = role
 
         /**
+         * The item type. An omitted type denotes a message. Tool call and output items have their
+         * corresponding tool type.
+         *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
          */
@@ -467,7 +467,7 @@ private constructor(
              */
             fun id(id: JsonField<String>) = apply { this.id = id }
 
-            /** The text input to the model. */
+            /** The required content of a message item. Tool call and output items omit content. */
             fun content(content: Content) = content(JsonField.of(content))
 
             /**
@@ -510,6 +510,10 @@ private constructor(
              */
             fun role(role: JsonValue) = apply { this.role = role }
 
+            /**
+             * The item type. An omitted type denotes a message. Tool call and output items have
+             * their corresponding tool type.
+             */
             fun type(type: Type) = type(JsonField.of(type))
 
             /**
@@ -579,14 +583,25 @@ private constructor(
                 return@apply
             }
 
-            id()
-            content().validate()
-            _role().let {
-                if (it != JsonValue.from("user")) {
-                    throw OpenAIInvalidDataException("'role' is invalid, received $it")
+            if (_type().isNull()) {
+                // The released Item validated null like an omitted type. Preserve its
+                // field checks without changing the wire value or newer item variants.
+                id()
+                content().validate()
+                _role().let {
+                    if (it != JsonValue.from("user")) {
+                        throw OpenAIInvalidDataException("'role' is invalid, received $it")
+                    }
+                }
+                type().ifPresent { it.validate() }
+            } else {
+                val properties = _allProperties()
+                com.openai.models.live.DecisionInputItemValidation.validate(properties)
+                // Stored items require an ID in the same wire properties we validated.
+                if (properties["id"]?.isNull() != false) {
+                    throw OpenAIInvalidDataException("Missing required 'id'")
                 }
             }
-            type().ifPresent { it.validate() }
             validated = true
         }
 
@@ -611,7 +626,7 @@ private constructor(
                 role.let { if (it == JsonValue.from("user")) 1 else 0 } +
                 (type.asKnown().getOrNull()?.validity() ?: 0)
 
-        /** The text input to the model. */
+        /** The required content of a message item. Tool call and output items omit content. */
         @JsonDeserialize(using = Content.Deserializer::class)
         @JsonSerialize(using = Content.Serializer::class)
         class Content
@@ -1822,6 +1837,10 @@ private constructor(
             }
         }
 
+        /**
+         * The item type. An omitted type denotes a message. Tool call and output items have their
+         * corresponding tool type.
+         */
         class Type @JsonCreator private constructor(private val value: JsonField<String>) : Enum {
 
             /**

@@ -475,37 +475,41 @@ private constructor(
          */
         fun visitRealtimeConversationItemSystemMessage(
             realtimeConversationItemSystemMessage: RealtimeConversationItemSystemMessage
-        ): T
+        ): T = unknown(JsonValue.from(realtimeConversationItemSystemMessage))
 
         /** A user message item in a Realtime conversation. */
         fun visitRealtimeConversationItemUserMessage(
             realtimeConversationItemUserMessage: RealtimeConversationItemUserMessage
-        ): T
+        ): T = unknown(JsonValue.from(realtimeConversationItemUserMessage))
 
         /** An assistant message item in a Realtime conversation. */
         fun visitRealtimeConversationItemAssistantMessage(
             realtimeConversationItemAssistantMessage: RealtimeConversationItemAssistantMessage
-        ): T
+        ): T = unknown(JsonValue.from(realtimeConversationItemAssistantMessage))
 
         /** A function call item in a Realtime conversation. */
-        fun visitFunctionCall(functionCall: RealtimeConversationItemFunctionCall): T
+        fun visitFunctionCall(functionCall: RealtimeConversationItemFunctionCall): T =
+            unknown(JsonValue.from(functionCall))
 
         /** A function call output item in a Realtime conversation. */
         fun visitFunctionCallOutput(
             functionCallOutput: RealtimeConversationItemFunctionCallOutput
-        ): T
+        ): T = unknown(JsonValue.from(functionCallOutput))
 
         /** A Realtime item responding to an MCP approval request. */
-        fun visitMcpApprovalResponse(mcpApprovalResponse: RealtimeMcpApprovalResponse): T
+        fun visitMcpApprovalResponse(mcpApprovalResponse: RealtimeMcpApprovalResponse): T =
+            unknown(JsonValue.from(mcpApprovalResponse))
 
         /** A Realtime item listing tools available on an MCP server. */
-        fun visitMcpListTools(mcpListTools: RealtimeMcpListTools): T
+        fun visitMcpListTools(mcpListTools: RealtimeMcpListTools): T =
+            unknown(JsonValue.from(mcpListTools))
 
         /** A Realtime item representing an invocation of a tool on an MCP server. */
-        fun visitMcpCall(mcpCall: RealtimeMcpToolCall): T
+        fun visitMcpCall(mcpCall: RealtimeMcpToolCall): T = unknown(JsonValue.from(mcpCall))
 
         /** A Realtime item requesting human approval of a tool invocation. */
-        fun visitMcpApprovalRequest(mcpApprovalRequest: RealtimeMcpApprovalRequest): T
+        fun visitMcpApprovalRequest(mcpApprovalRequest: RealtimeMcpApprovalRequest): T =
+            unknown(JsonValue.from(mcpApprovalRequest))
 
         /**
          * Maps an unknown variant of [ConversationItem] to a value of type [T].
@@ -515,6 +519,9 @@ private constructor(
          * version than the API, then the API may respond with new variants that the SDK is unaware
          * of.
          *
+         * Recognized variants also reach this method when their visit method is not overridden.
+         * This allows existing visitors to handle variants added by newer SDK versions.
+         *
          * @throws OpenAIInvalidDataException in the default implementation.
          */
         fun unknown(json: JsonValue?): T {

@@ -58,6 +58,9 @@ interface OrganizationServiceAsync {
     fun dataRetention(): DataRetentionServiceAsync =
         throw UnsupportedOperationException("Subservice is not supported by this implementation")
 
+    fun externalKeys(): ExternalKeyServiceAsync =
+        throw UnsupportedOperationException("Subservice is not supported by this implementation")
+
     fun externalStorage(): ExternalStorageServiceAsync =
         throw UnsupportedOperationException("Subservice is not supported by this implementation")
 
@@ -73,9 +76,6 @@ interface OrganizationServiceAsync {
     fun projects(): ProjectServiceAsync =
         throw UnsupportedOperationException("Subservice is not supported by this implementation")
 
-    fun externalKeys(): ExternalKeyServiceAsync =
-        throw UnsupportedOperationException("Subservice is not supported by this implementation")
-
     /**
      * A view of [OrganizationServiceAsync] that provides access to raw HTTP responses for each
      * method.
@@ -132,6 +132,11 @@ interface OrganizationServiceAsync {
                 "Subservice is not supported by this implementation"
             )
 
+        fun externalKeys(): ExternalKeyServiceAsync.WithRawResponse =
+            throw UnsupportedOperationException(
+                "Subservice is not supported by this implementation"
+            )
+
         fun externalStorage(): ExternalStorageServiceAsync.WithRawResponse =
             throw UnsupportedOperationException(
                 "Subservice is not supported by this implementation"
@@ -156,10 +161,5 @@ interface OrganizationServiceAsync {
             throw UnsupportedOperationException(
                 "Subservice is not supported by this implementation"
             )
-
-        fun externalKeys(): ExternalKeyServiceAsync.WithRawResponse =
-            throw UnsupportedOperationException(
-                "Subservice is not supported by this implementation"
-            )
     }
 }