release: 0.42.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.41.1"
+  ".": "0.42.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 80
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-6663c59193eb95b201e492de17dcbd5e126ba03d18ce66287a3e2c632ca56fe7.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-4bce8217a697c729ac98046d4caf2c9e826b54c427fb0ab4f98e549a2e0ce31c.yml
 openapi_spec_hash: 7996d2c34cc44fe2ce9ffe93c0ab774e
-config_hash: 2daae06cc598821ccf87201de0861e40
+config_hash: 178ba1bfb1237bf6b94abb3408072aa7

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.42.0 (2025-04-02)
+
+Full Changelog: [v0.41.1...v0.42.0](https://github.com/openai/openai-java/compare/v0.41.1...v0.42.0)
+
+### Features
+
+* **api:** manual updates ([0440105](https://github.com/openai/openai-java/commit/0440105162ce52cd187ce8ab8d5d1dc20682a4ed))
+* **client:** add enum validation method ([a641218](https://github.com/openai/openai-java/commit/a6412183ccea1ac3e9105793372693d5ec8c6d72))
+* **client:** make union deserialization more robust ([#385](https://github.com/openai/openai-java/issues/385)) ([a641218](https://github.com/openai/openai-java/commit/a6412183ccea1ac3e9105793372693d5ec8c6d72))
+
+
+### Chores
+
+* **client:** remove unnecessary json state from some query param classes ([a641218](https://github.com/openai/openai-java/commit/a6412183ccea1ac3e9105793372693d5ec8c6d72))
+* **internal:** add invalid json deserialization tests ([a641218](https://github.com/openai/openai-java/commit/a6412183ccea1ac3e9105793372693d5ec8c6d72))
+* **internal:** add json roundtripping tests ([a641218](https://github.com/openai/openai-java/commit/a6412183ccea1ac3e9105793372693d5ec8c6d72))
+
 ## 0.41.1 (2025-04-01)
 
 Full Changelog: [v0.41.0...v0.41.1](https://github.com/openai/openai-java/compare/v0.41.0...v0.41.1)

README.md

@@ -9,16 +9,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/0.41.1)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.41.1/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.41.1)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.42.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.42.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.42.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 also available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/0.41.1).
+The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are also available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/0.42.0).
 
 <!-- x-release-please-end -->
 
@@ -29,7 +29,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:0.41.1")
+implementation("com.openai:openai-java:0.42.0")
 ```
 
 ### Maven
@@ -38,7 +38,7 @@ implementation("com.openai:openai-java:0.41.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java</artifactId>
-  <version>0.41.1</version>
+  <version>0.42.0</version>
 </dependency>
 ```
 

build.gradle.kts

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

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

@@ -7,11 +7,9 @@ import com.fasterxml.jackson.databind.BeanProperty
 import com.fasterxml.jackson.databind.DeserializationContext
 import com.fasterxml.jackson.databind.JavaType
 import com.fasterxml.jackson.databind.JsonDeserializer
-import com.fasterxml.jackson.databind.JsonMappingException
 import com.fasterxml.jackson.databind.JsonNode
 import com.fasterxml.jackson.databind.deser.ContextualDeserializer
 import com.fasterxml.jackson.databind.deser.std.StdDeserializer
-import com.openai.errors.OpenAIInvalidDataException
 import kotlin.reflect.KClass
 
 abstract class BaseDeserializer<T : Any>(type: KClass<T>) :
@@ -30,38 +28,17 @@ abstract class BaseDeserializer<T : Any>(type: KClass<T>) :
 
     protected abstract fun ObjectCodec.deserialize(node: JsonNode): T
 
-    protected fun <T> ObjectCodec.deserialize(node: JsonNode, type: TypeReference<T>): T =
+    protected fun <T> ObjectCodec.tryDeserialize(node: JsonNode, type: TypeReference<T>): T? =
         try {
             readValue(treeAsTokens(node), type)
         } catch (e: Exception) {
-            throw OpenAIInvalidDataException("Error deserializing", e)
-        }
-
-    protected fun <T> ObjectCodec.tryDeserialize(
-        node: JsonNode,
-        type: TypeReference<T>,
-        validate: (T) -> Unit = {},
-    ): T? {
-        return try {
-            readValue(treeAsTokens(node), type).apply(validate)
-        } catch (e: JsonMappingException) {
-            null
-        } catch (e: RuntimeException) {
             null
         }
-    }
 
-    protected fun <T> ObjectCodec.tryDeserialize(
-        node: JsonNode,
-        type: JavaType,
-        validate: (T) -> Unit = {},
-    ): T? {
-        return try {
-            readValue<T>(treeAsTokens(node), type).apply(validate)
-        } catch (e: JsonMappingException) {
-            null
-        } catch (e: RuntimeException) {
+    protected fun <T> ObjectCodec.tryDeserialize(node: JsonNode, type: JavaType): T? =
+        try {
+            readValue(treeAsTokens(node), type)
+        } catch (e: Exception) {
             null
         }
-    }
 }

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

@@ -25,6 +25,34 @@ internal fun <K : Comparable<K>, V> SortedMap<K, V>.toImmutable(): SortedMap<K,
     if (isEmpty()) Collections.emptySortedMap()
     else Collections.unmodifiableSortedMap(toSortedMap(comparator()))
 
+/**
+ * Returns all elements that yield the largest value for the given function, or an empty list if
+ * there are zero elements.
+ *
+ * This is similar to [Sequence.maxByOrNull] except it returns _all_ elements that yield the largest
+ * value; not just the first one.
+ */
+@JvmSynthetic
+internal fun <T, R : Comparable<R>> Sequence<T>.allMaxBy(selector: (T) -> R): List<T> {
+    var maxValue: R? = null
+    val maxElements = mutableListOf<T>()
+
+    val iterator = iterator()
+    while (iterator.hasNext()) {
+        val element = iterator.next()
+        val value = selector(element)
+        if (maxValue == null || value > maxValue) {
+            maxValue = value
+            maxElements.clear()
+            maxElements.add(element)
+        } else if (value == maxValue) {
+            maxElements.add(element)
+        }
+    }
+
+    return maxElements
+}
+
 /**
  * Returns whether [this] is equal to [other].
  *

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

@@ -15,6 +15,7 @@ import com.openai.core.BaseSerializer
 import com.openai.core.Enum
 import com.openai.core.JsonField
 import com.openai.core.JsonValue
+import com.openai.core.allMaxBy
 import com.openai.core.getOrThrow
 import com.openai.errors.OpenAIInvalidDataException
 import java.util.Objects
@@ -50,14 +51,13 @@ private constructor(
 
     fun _json(): Optional<JsonValue> = Optional.ofNullable(_json)
 
-    fun <T> accept(visitor: Visitor<T>): T {
-        return when {
+    fun <T> accept(visitor: Visitor<T>): T =
+        when {
             string != null -> visitor.visitString(string)
             chatModel != null -> visitor.visitChatModel(chatModel)
             unionMember2 != null -> visitor.visitUnionMember2(unionMember2)
             else -> visitor.unknown(_json)
         }
-    }
 
     private var validated: Boolean = false
 
@@ -70,14 +70,45 @@ private constructor(
             object : Visitor<Unit> {
                 override fun visitString(string: String) {}
 
-                override fun visitChatModel(chatModel: ChatModel) {}
+                override fun visitChatModel(chatModel: ChatModel) {
+                    chatModel.validate()
+                }
 
-                override fun visitUnionMember2(unionMember2: UnionMember2) {}
+                override fun visitUnionMember2(unionMember2: UnionMember2) {
+                    unionMember2.validate()
+                }
             }
         )
         validated = true
     }
 
+    fun isValid(): Boolean =
+        try {
+            validate()
+            true
+        } catch (e: OpenAIInvalidDataException) {
+            false
+        }
+
+    /**
+     * Returns a score indicating how many valid values are contained in this object recursively.
+     *
+     * Used for best match union deserialization.
+     */
+    @JvmSynthetic
+    internal fun validity(): Int =
+        accept(
+            object : Visitor<Int> {
+                override fun visitString(string: String) = 1
+
+                override fun visitChatModel(chatModel: ChatModel) = chatModel.validity()
+
+                override fun visitUnionMember2(unionMember2: UnionMember2) = unionMember2.validity()
+
+                override fun unknown(json: JsonValue?) = 0
+            }
+        )
+
     override fun equals(other: Any?): Boolean {
         if (this === other) {
             return true
@@ -135,17 +166,30 @@ private constructor(
         override fun ObjectCodec.deserialize(node: JsonNode): AllModels {
             val json = JsonValue.fromJsonNode(node)
 
-            tryDeserialize(node, jacksonTypeRef<String>())?.let {
-                return AllModels(string = it, _json = json)
-            }
-            tryDeserialize(node, jacksonTypeRef<ChatModel>())?.let {
-                return AllModels(chatModel = it, _json = json)
-            }
-            tryDeserialize(node, jacksonTypeRef<UnionMember2>())?.let {
-                return AllModels(unionMember2 = it, _json = json)
+            val bestMatches =
+                sequenceOf(
+                        tryDeserialize(node, jacksonTypeRef<ChatModel>())?.let {
+                            AllModels(chatModel = it, _json = json)
+                        },
+                        tryDeserialize(node, jacksonTypeRef<UnionMember2>())?.let {
+                            AllModels(unionMember2 = it, _json = json)
+                        },
+                        tryDeserialize(node, jacksonTypeRef<String>())?.let {
+                            AllModels(string = it, _json = json)
+                        },
+                    )
+                    .filterNotNull()
+                    .allMaxBy { it.validity() }
+                    .toList()
+            return when (bestMatches.size) {
+                // This can happen if what we're deserializing is completely incompatible with all
+                // the possible variants (e.g. deserializing from object).
+                0 -> AllModels(_json = json)
+                1 -> bestMatches.single()
+                // If there's more than one match with the highest validity, then use the first
+                // completely valid match, or simply the first match if none are completely valid.
+                else -> bestMatches.firstOrNull { it.isValid() } ?: bestMatches.first()
             }
-
-            return AllModels(_json = json)
         }
     }
 
@@ -266,6 +310,33 @@ private constructor(
         fun asString(): String =
             _value().asString().orElseThrow { OpenAIInvalidDataException("Value is not a String") }
 
+        private var validated: Boolean = false
+
+        fun validate(): UnionMember2 = apply {
+            if (validated) {
+                return@apply
+            }
+
+            known()
+            validated = true
+        }
+
+        fun isValid(): Boolean =
+            try {
+                validate()
+                true
+            } catch (e: OpenAIInvalidDataException) {
+                false
+            }
+
+        /**
+         * Returns a score indicating how many valid values are contained in this object
+         * recursively.
+         *
+         * Used for best match union deserialization.
+         */
+        @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1
+
         override fun equals(other: Any?): Boolean {
             if (this === other) {
                 return true

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

@@ -338,6 +338,32 @@ class ChatModel @JsonCreator private constructor(private val value: JsonField<St
     fun asString(): String =
         _value().asString().orElseThrow { OpenAIInvalidDataException("Value is not a String") }
 
+    private var validated: Boolean = false
+
+    fun validate(): ChatModel = apply {
+        if (validated) {
+            return@apply
+        }
+
+        known()
+        validated = true
+    }
+
+    fun isValid(): Boolean =
+        try {
+            validate()
+            true
+        } catch (e: OpenAIInvalidDataException) {
+            false
+        }
+
+    /**
+     * Returns a score indicating how many valid values are contained in this object recursively.
+     *
+     * Used for best match union deserialization.
+     */
+    @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1
+
     override fun equals(other: Any?): Boolean {
         if (this === other) {
             return true