release: 3.3.0 (#606)

* feat(client): support verbosity with structured outputs (#603)

* verbosity: structured output support for verbosity #576

* verbosity: minor doc fixes

* release: 3.3.0

---------

Co-authored-by: D Gardner <[email protected]>
Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.2.1"
+  ".": "3.3.0"
 }

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.3.0 (2025-09-03)
+
+Full Changelog: [v3.2.1...v3.3.0](https://github.com/openai/openai-java/compare/v3.2.1...v3.3.0)
+
+### Features
+
+* **client:** support verbosity with structured outputs ([#603](https://github.com/openai/openai-java/issues/603)) ([2496464](https://github.com/openai/openai-java/commit/24964646ab02a3ff61efb9802facac66b204bdaf))
+
 ## 3.2.1 (2025-09-02)
 
 Full Changelog: [v3.2.0...v3.2.1](https://github.com/openai/openai-java/compare/v3.2.0...v3.2.1)

README.md

@@ -2,16 +2,16 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/3.2.1)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/3.2.1/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/3.2.1)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/3.3.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/3.3.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/3.3.0)
 
 <!-- x-release-please-end -->
 
 The OpenAI Java SDK provides convenient access to the [OpenAI REST API](https://platform.openai.com/docs) from applications written in Java.
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/3.2.1).
+The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/3.3.0).
 
 <!-- x-release-please-end -->
 
@@ -24,7 +24,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:3.2.1")
+implementation("com.openai:openai-java:3.3.0")
 ```
 
 ### Maven
@@ -33,7 +33,7 @@ implementation("com.openai:openai-java:3.2.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java</artifactId>
-  <version>3.2.1</version>
+  <version>3.3.0</version>
 </dependency>
 ```
 
@@ -565,6 +565,18 @@ the latter when `ResponseCreateParams.Builder.text(Class<T>)` is called.
 For a full example of the usage of _Structured Outputs_ with the Responses API, see
 [`ResponsesStructuredOutputsExample`](openai-java-example/src/main/java/com/openai/example/ResponsesStructuredOutputsExample.java).
 
+Instead of using `ResponseCreateParams.text(Class<T>)`, you can build a
+[`StructuredResponseTextConfig`](openai-java-core/src/main/kotlin/com/openai/models/responses/StructuredResponseTextConfig.kt)
+and set it on the `ResponseCreateParams` using the `text(StructuredResponseTextConfig)` method.
+Similar to using `ResponseCreateParams`, you can start with a `ResponseTextConfig.Builder` and its
+`format(Class<T>)` method will change it to a `StructuredResponseTextConfig.Builder`. This also
+allows you to set the `verbosity` configuration parameter on the text configuration before adding it
+to the `ResponseCreateParams`.
+
+For a full example of the usage of _Structured Outputs_ with the `ResponseTextConfig` and its
+`verbosity` parameter, see
+[`ResponsesStructuredOutputsVerbosityExample`](openai-java-example/src/main/java/com/openai/example/ResponsesStructuredOutputsVerbosityExample.java).
+
 ### Usage with streaming
 
 _Structured Outputs_ can also be used with [Streaming](#streaming) and the Chat Completions API. As
@@ -1330,7 +1342,7 @@ If you're using Spring Boot, then you can use the SDK's [Spring Boot starter](ht
 #### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java-spring-boot-starter:3.2.1")
+implementation("com.openai:openai-java-spring-boot-starter:3.3.0")
 ```
 
 #### Maven
@@ -1339,7 +1351,7 @@ implementation("com.openai:openai-java-spring-boot-starter:3.2.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java-spring-boot-starter</artifactId>
-  <version>3.2.1</version>
+  <version>3.3.0</version>
 </dependency>
 ```
 

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "3.2.1" // x-release-please-version
+    version = "3.3.0" // x-release-please-version
 }
 
 subprojects {

openai-java-core/src/main/kotlin/com/openai/core/JsonSchemaValidator.kt

@@ -312,7 +312,7 @@ internal class JsonSchemaValidator private constructor() {
 
     /**
      * Validates a schema if it has an `"anyOf"` field. OpenAI does not support the use of `"anyOf"`
-     * at the root of a JSON schema. The value is the field is expected to be an array of valid
+     * at the root of a JSON schema. The value of the field is expected to be an array of valid
      * sub-schemas. If the schema has no `"anyOf"` field, no action is taken.
      */
     private fun validateAnyOfSchema(schema: JsonNode, path: String, depth: Int) {

openai-java-core/src/main/kotlin/com/openai/core/StructuredOutputs.kt

@@ -85,6 +85,20 @@ internal fun validateSchema(
     return schema
 }
 
+/** Builds a text configuration's JSON schema, deriving it from the structure of a class. */
+@JvmSynthetic
+internal fun jsonSchemaFromClass(
+    type: Class<*>,
+    localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
+): ResponseFormatTextJsonSchemaConfig =
+    ResponseFormatTextJsonSchemaConfig.builder()
+        .name("json-schema-from-${type.simpleName}")
+        .schema(JsonValue.fromJsonNode(validateSchema(extractSchema(type), type, localValidation)))
+        // Ensure the model's output strictly adheres to this JSON schema. This is the essential
+        // "ON switch" for Structured Outputs.
+        .strict(true)
+        .build()
+
 /**
  * Builds a text configuration with its format set to a JSON schema derived from the structure of an
  * arbitrary Java class.
@@ -94,21 +108,7 @@ internal fun textConfigFromClass(
     type: Class<*>,
     localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
 ): ResponseTextConfig =
-    ResponseTextConfig.builder()
-        .format(
-            ResponseFormatTextJsonSchemaConfig.builder()
-                .name("json-schema-from-${type.simpleName}")
-                .schema(
-                    JsonValue.fromJsonNode(
-                        validateSchema(extractSchema(type), type, localValidation)
-                    )
-                )
-                // Ensure the model's output strictly adheres to this JSON schema. This is the
-                // essential "ON switch" for Structured Outputs.
-                .strict(true)
-                .build()
-        )
-        .build()
+    ResponseTextConfig.builder().format(jsonSchemaFromClass(type, localValidation)).build()
 
 // "internal" instead of "private" for testing purposes.
 internal data class FunctionInfo(

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt

@@ -267,7 +267,7 @@ private constructor(
          * Gets the arguments to the function call, converting the values from the model in JSON
          * format to an instance of a class that holds those values. The class must previously have
          * been used to define the JSON schema for the function definition's parameters, so that the
-         * JSON corresponds to structure of the given class.
+         * JSON corresponds to the structure of the given class.
          *
          * @throws OpenAIInvalidDataException If the JSON data is missing, `null`, or cannot be
          *   parsed to an instance of the [functionParametersType] class. This might occur if the

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/StructuredChatCompletionCreateParams.kt

@@ -15,7 +15,7 @@ import java.util.Optional
 /**
  * A wrapper for [ChatCompletionCreateParams] that provides a type-safe [Builder] that can record
  * the [responseType] used to derive a JSON schema from an arbitrary class when using the
- * _Structured Outputs_ feature. When a JSON response is received, it is deserialized to am instance
+ * _Structured Outputs_ feature. When a JSON response is received, it is deserialized to an instance
  * of that type. See the SDK documentation for more details on _Structured Outputs_.
  *
  * @param T The type of the class that will be used to derive the JSON schema in the request and to

openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt

@@ -1098,6 +1098,8 @@ private constructor(
          * [StructuredResponseCreateParams.Builder] that will build a
          * [StructuredResponseCreateParams] instance when `build()` is called.
          *
+         * Use this method or the `text(StructuredResponseTextConfig<T>)` method, but not both.
+         *
          * @param responseType A class from which a JSON schema will be derived to define the text
          *   configuration's format.
          * @param localValidation [JsonSchemaLocalValidation.YES] (the default) to validate the JSON
@@ -1114,6 +1116,21 @@ private constructor(
             localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
         ) = StructuredResponseCreateParams.builder<T>().wrap(responseType, this, localValidation)
 
+        /**
+         * Sets the text configuration to a [StructuredResponseTextConfig] where the format was set
+         * to a JSON schema derived from the structure of a class. This changes the builder to a
+         * type-safe [StructuredResponseCreateParams.Builder] that will build a
+         * [StructuredResponseCreateParams] instance when `build()` is called.
+         *
+         * Use this method or the `text(Class<T>)` method, but not both.
+         *
+         * @param text A text configuration in which the JSON schema defining the format was derived
+         *   from the structure of a class. The `verbosity` parameter can also be set on the text
+         *   configuration, if required.
+         */
+        fun <T : Any> text(text: StructuredResponseTextConfig<T>) =
+            StructuredResponseCreateParams.builder<T>().wrap(text, this)
+
         /**
          * How the model should select which tool (or tools) to use when generating a response. See
          * the `tools` parameter to see how to specify which tools the model can call.

openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt

@@ -10,6 +10,7 @@ import com.openai.core.Enum
 import com.openai.core.ExcludeMissing
 import com.openai.core.JsonField
 import com.openai.core.JsonMissing
+import com.openai.core.JsonSchemaLocalValidation
 import com.openai.core.JsonValue
 import com.openai.errors.OpenAIInvalidDataException
 import com.openai.models.ResponseFormatJsonObject
@@ -157,6 +158,28 @@ private constructor(
         fun format(jsonObject: ResponseFormatJsonObject) =
             format(ResponseFormatTextConfig.ofJsonObject(jsonObject))
 
+        /**
+         * Sets the text configuration's format to a JSON schema derived from the structure of the
+         * given class. This changes the builder to a type-safe
+         * [StructuredResponseTextConfig.Builder] that will build a [StructuredResponseTextConfig]
+         * instance when `build()` is called.
+         *
+         * @param responseType A class from which a JSON schema will be derived to define the text
+         *   configuration's format.
+         * @param localValidation [JsonSchemaLocalValidation.YES] (the default) to validate the JSON
+         *   schema locally when it is generated by this method to confirm that it adheres to the
+         *   requirements and restrictions on JSON schemas imposed by the OpenAI specification; or
+         *   [JsonSchemaLocalValidation.NO] to skip local validation and rely only on remote
+         *   validation. See the SDK documentation for more details.
+         * @throws IllegalArgumentException If local validation is enabled, but it fails because a
+         *   valid JSON schema cannot be derived from the given class.
+         */
+        @JvmOverloads
+        fun <T : Any> format(
+            responseType: Class<T>,
+            localValidation: JsonSchemaLocalValidation = JsonSchemaLocalValidation.YES,
+        ) = StructuredResponseTextConfig.builder<T>().wrap(responseType, this, localValidation)
+
         /**
          * Constrains the verbosity of the model's response. Lower values will result in more
          * concise responses, while higher values will result in more verbose responses. Currently