release: 0.37.0 (#356)

* chore(internal): fix example formatting (#348)

* chore(internal): remove unnecessary import (#349)

* docs: update readme exception docs (#350)

* docs: minor readme tweak (#351)

* docs: responses image url example

* feat(client): support a lower jackson version (#357)

feat(client): throw on incompatible jackson version

* release: 0.37.0

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Tomer Aberbach <tomer@stainless.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.36.0"
+  ".": "0.37.0"
 }

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.37.0 (2025-03-25)
+
+Full Changelog: [v0.36.0...v0.37.0](https://github.com/openai/openai-java/compare/v0.36.0...v0.37.0)
+
+### Features
+
+* **client:** support a lower jackson version ([#357](https://github.com/openai/openai-java/issues/357)) ([13a3c67](https://github.com/openai/openai-java/commit/13a3c672ef093f4a0e9110ce716086f4a3ea4329))
+* **client:** throw on incompatible jackson version ([13a3c67](https://github.com/openai/openai-java/commit/13a3c672ef093f4a0e9110ce716086f4a3ea4329))
+
+
+### Chores
+
+* **internal:** fix example formatting ([#348](https://github.com/openai/openai-java/issues/348)) ([44a7df9](https://github.com/openai/openai-java/commit/44a7df9af13ab14947fd50b37a7d26b1d9c5d0df))
+* **internal:** remove unnecessary import ([#349](https://github.com/openai/openai-java/issues/349)) ([661a906](https://github.com/openai/openai-java/commit/661a9060183a645b9ec7f9687fa0786adb224283))
+
+
+### Documentation
+
+* minor readme tweak ([#351](https://github.com/openai/openai-java/issues/351)) ([28a1116](https://github.com/openai/openai-java/commit/28a111615345011335e73f2894f1f54672493cdf))
+* responses image url example ([d84abd4](https://github.com/openai/openai-java/commit/d84abd426d220b1c248bc31cf9f47dfeb9e25509))
+* update readme exception docs ([#350](https://github.com/openai/openai-java/issues/350)) ([b441223](https://github.com/openai/openai-java/commit/b441223dc8c26d7fc023614f6b15610b8f7af35d))
+
 ## 0.36.0 (2025-03-21)
 
 Full Changelog: [v0.35.1...v0.36.0](https://github.com/openai/openai-java/compare/v0.35.1...v0.36.0)

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.36.0)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.36.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.36.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.37.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.37.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.37.0)
 
 <!-- x-release-please-end -->
 
-The OpenAI Java SDK provides convenient access to the OpenAI REST API from applications written in Java.
+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.36.0).
+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.37.0).
 
 <!-- x-release-please-end -->
 
@@ -29,16 +29,16 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:0.36.0")
+implementation("com.openai:openai-java:0.37.0")
 ```
 
 ### Maven
 
 ```xml
 <dependency>
-    <groupId>com.openai</groupId>
-    <artifactId>openai-java</artifactId>
-    <version>0.36.0</version>
+  <groupId>com.openai</groupId>
+  <artifactId>openai-java</artifactId>
+  <version>0.37.0</version>
 </dependency>
 ```
 
@@ -444,16 +444,18 @@ The SDK throws custom unchecked exception types:
 
 - [`OpenAIServiceException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIServiceException.kt): Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:
 
-  | Status | Exception                       |
-  | ------ | ------------------------------- |
-  | 400    | `BadRequestException`           |
-  | 401    | `AuthenticationException`       |
-  | 403    | `PermissionDeniedException`     |
-  | 404    | `NotFoundException`             |
-  | 422    | `UnprocessableEntityException`  |
-  | 429    | `RateLimitException`            |
-  | 5xx    | `InternalServerException`       |
-  | others | `UnexpectedStatusCodeException` |
+  | Status | Exception                                                                                                              |
+  | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+  | 400    | [`BadRequestException`](openai-java-core/src/main/kotlin/com/openai/errors/BadRequestException.kt)                     |
+  | 401    | [`UnauthorizedException`](openai-java-core/src/main/kotlin/com/openai/errors/UnauthorizedException.kt)                 |
+  | 403    | [`PermissionDeniedException`](openai-java-core/src/main/kotlin/com/openai/errors/PermissionDeniedException.kt)         |
+  | 404    | [`NotFoundException`](openai-java-core/src/main/kotlin/com/openai/errors/NotFoundException.kt)                         |
+  | 422    | [`UnprocessableEntityException`](openai-java-core/src/main/kotlin/com/openai/errors/UnprocessableEntityException.kt)   |
+  | 429    | [`RateLimitException`](openai-java-core/src/main/kotlin/com/openai/errors/RateLimitException.kt)                       |
+  | 5xx    | [`InternalServerException`](openai-java-core/src/main/kotlin/com/openai/errors/InternalServerException.kt)             |
+  | others | [`UnexpectedStatusCodeException`](openai-java-core/src/main/kotlin/com/openai/errors/UnexpectedStatusCodeException.kt) |
+
+  [`SseException`](openai-java-core/src/main/kotlin/com/openai/errors/SseException.kt) is thrown for errors encountered during [SSE streaming](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) after a successful initial HTTP response.
 
 - [`OpenAIIoException`](openai-java-core/src/main/kotlin/com/openai/errors/OpenAIIoException.kt): I/O networking errors.
 

build.gradle.kts

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

openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt

@@ -41,6 +41,17 @@ class OpenAIOkHttpClient private constructor() {
             this.baseUrl = baseUrl
         }
 
+        /**
+         * Whether to throw an exception if any of the Jackson versions detected at runtime are
+         * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+         *
+         * Defaults to true. Use extreme caution when disabling this option. There is no guarantee
+         * that the SDK will work correctly when using an incompatible Jackson version.
+         */
+        fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+            clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
+        }
+
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
         fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {

openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt

@@ -41,6 +41,17 @@ class OpenAIOkHttpClientAsync private constructor() {
             this.baseUrl = baseUrl
         }
 
+        /**
+         * Whether to throw an exception if any of the Jackson versions detected at runtime are
+         * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+         *
+         * Defaults to true. Use extreme caution when disabling this option. There is no guarantee
+         * that the SDK will work correctly when using an incompatible Jackson version.
+         */
+        fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+            clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
+        }
+
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
         fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {

openai-java-core/build.gradle.kts

@@ -3,6 +3,19 @@ plugins {
     id("openai.publish")
 }
 
+configurations.all {
+    resolutionStrategy {
+        // Compile and test against a lower Jackson version to ensure we're compatible with it.
+        // We publish with a higher version (see below) to ensure users depend on a secure version by default.
+        force("com.fasterxml.jackson.core:jackson-core:2.13.4")
+        force("com.fasterxml.jackson.core:jackson-databind:2.13.4")
+        force("com.fasterxml.jackson.core:jackson-annotations:2.13.4")
+        force("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.13.4")
+        force("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.13.4")
+        force("com.fasterxml.jackson.module:jackson-module-kotlin:2.13.4")
+    }
+}
+
 dependencies {
     api("com.fasterxml.jackson.core:jackson-core:2.18.1")
     api("com.fasterxml.jackson.core:jackson-databind:2.18.1")

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

@@ -2,6 +2,9 @@
 
 package com.openai.core
 
+import com.fasterxml.jackson.core.Version
+import com.fasterxml.jackson.core.util.VersionUtil
+
 fun <T : Any> checkRequired(name: String, value: T?): T =
     checkNotNull(value) { "`$name` is required, but was not set" }
 
@@ -39,3 +42,46 @@ internal fun checkMaxLength(name: String, value: String, maxLength: Int): String
             "`$name` must have at most length $maxLength, but was ${it.length}"
         }
     }
+
+@JvmSynthetic
+internal fun checkJacksonVersionCompatibility() {
+    val incompatibleJacksonVersions =
+        RUNTIME_JACKSON_VERSIONS.mapNotNull {
+            when {
+                it.majorVersion != MINIMUM_JACKSON_VERSION.majorVersion ->
+                    it to "incompatible major version"
+                it.minorVersion < MINIMUM_JACKSON_VERSION.minorVersion ->
+                    it to "minor version too low"
+                it.minorVersion == MINIMUM_JACKSON_VERSION.minorVersion &&
+                    it.patchLevel < MINIMUM_JACKSON_VERSION.patchLevel ->
+                    it to "patch version too low"
+                else -> null
+            }
+        }
+    check(incompatibleJacksonVersions.isEmpty()) {
+        """
+This SDK depends on Jackson version $MINIMUM_JACKSON_VERSION, but the following incompatible Jackson versions were detected at runtime:
+
+${incompatibleJacksonVersions.asSequence().map { (version, incompatibilityReason) ->
+    "- `${version.toFullString().replace("/", ":")}` ($incompatibilityReason)"
+}.joinToString("\n")}
+
+This can happen if you are either:
+1. Directly depending on different Jackson versions
+2. Depending on some library that depends on different Jackson versions, potentially transitively
+
+Double-check that you are depending on compatible Jackson versions.
+        """
+            .trimIndent()
+    }
+}
+
+private val MINIMUM_JACKSON_VERSION: Version = VersionUtil.parseVersion("2.13.4", null, null)
+private val RUNTIME_JACKSON_VERSIONS: List<Version> =
+    listOf(
+        com.fasterxml.jackson.core.json.PackageVersion.VERSION,
+        com.fasterxml.jackson.databind.cfg.PackageVersion.VERSION,
+        com.fasterxml.jackson.datatype.jdk8.PackageVersion.VERSION,
+        com.fasterxml.jackson.datatype.jsr310.PackageVersion.VERSION,
+        com.fasterxml.jackson.module.kotlin.PackageVersion.VERSION,
+    )

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

@@ -24,6 +24,7 @@ class ClientOptions
 private constructor(
     private val originalHttpClient: HttpClient,
     @get:JvmName("httpClient") val httpClient: HttpClient,
+    @get:JvmName("checkJacksonVersionCompatibility") val checkJacksonVersionCompatibility: Boolean,
     @get:JvmName("jsonMapper") val jsonMapper: JsonMapper,
     @get:JvmName("streamHandlerExecutor") val streamHandlerExecutor: Executor,
     @get:JvmName("clock") val clock: Clock,
@@ -38,6 +39,12 @@ private constructor(
     private val project: String?,
 ) {
 
+    init {
+        if (checkJacksonVersionCompatibility) {
+            checkJacksonVersionCompatibility()
+        }
+    }
+
     fun organization(): Optional<String> = Optional.ofNullable(organization)
 
     fun project(): Optional<String> = Optional.ofNullable(project)
@@ -66,6 +73,7 @@ private constructor(
     class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null
+        private var checkJacksonVersionCompatibility: Boolean = true
         private var jsonMapper: JsonMapper = jsonMapper()
         private var streamHandlerExecutor: Executor? = null
         private var clock: Clock = Clock.systemUTC()
@@ -83,6 +91,7 @@ private constructor(
         @JvmSynthetic
         internal fun from(clientOptions: ClientOptions) = apply {
             httpClient = clientOptions.originalHttpClient
+            checkJacksonVersionCompatibility = clientOptions.checkJacksonVersionCompatibility
             jsonMapper = clientOptions.jsonMapper
             streamHandlerExecutor = clientOptions.streamHandlerExecutor
             clock = clientOptions.clock
@@ -99,6 +108,10 @@ private constructor(
 
         fun httpClient(httpClient: HttpClient) = apply { this.httpClient = httpClient }
 
+        fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+            this.checkJacksonVersionCompatibility = checkJacksonVersionCompatibility
+        }
+
         fun jsonMapper(jsonMapper: JsonMapper) = apply { this.jsonMapper = jsonMapper }
 
         fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {
@@ -312,6 +325,7 @@ private constructor(
                         .maxRetries(maxRetries)
                         .build()
                 ),
+                checkJacksonVersionCompatibility,
                 jsonMapper,
                 streamHandlerExecutor
                     ?: Executors.newCachedThreadPool(

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

@@ -5,23 +5,19 @@ package com.openai.core
 import com.fasterxml.jackson.annotation.JsonInclude
 import com.fasterxml.jackson.core.JsonGenerator
 import com.fasterxml.jackson.databind.DeserializationFeature
+import com.fasterxml.jackson.databind.MapperFeature
 import com.fasterxml.jackson.databind.SerializationFeature
 import com.fasterxml.jackson.databind.SerializerProvider
-import com.fasterxml.jackson.databind.cfg.CoercionAction.Fail
-import com.fasterxml.jackson.databind.cfg.CoercionInputShape.Integer
-import com.fasterxml.jackson.databind.exc.InvalidDefinitionException
-import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.databind.module.SimpleModule
 import com.fasterxml.jackson.datatype.jdk8.Jdk8Module
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule
-import com.fasterxml.jackson.module.kotlin.jacksonMapperBuilder
-import com.openai.errors.OpenAIException
-import com.openai.errors.OpenAIInvalidDataException
+import com.fasterxml.jackson.module.kotlin.kotlinModule
 import java.io.InputStream
 
 fun jsonMapper(): JsonMapper =
-    jacksonMapperBuilder()
+    JsonMapper.builder()
+        .addModule(kotlinModule())
         .addModule(Jdk8Module())
         .addModule(JavaTimeModule())
         .addModule(SimpleModule().addSerializer(InputStreamJsonSerializer))
@@ -30,7 +26,12 @@ fun jsonMapper(): JsonMapper =
         .disable(SerializationFeature.FLUSH_AFTER_WRITE_VALUE)
         .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
         .disable(SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS)
-        .withCoercionConfig(String::class.java) { it.setCoercion(Integer, Fail) }
+        .disable(MapperFeature.ALLOW_COERCION_OF_SCALARS)
+        .disable(MapperFeature.AUTO_DETECT_CREATORS)
+        .disable(MapperFeature.AUTO_DETECT_FIELDS)
+        .disable(MapperFeature.AUTO_DETECT_GETTERS)
+        .disable(MapperFeature.AUTO_DETECT_IS_GETTERS)
+        .disable(MapperFeature.AUTO_DETECT_SETTERS)
         .build()
 
 private object InputStreamJsonSerializer : BaseSerializer<InputStream>(InputStream::class) {
@@ -47,38 +48,3 @@ private object InputStreamJsonSerializer : BaseSerializer<InputStream>(InputStre
         }
     }
 }
-
-@JvmSynthetic
-internal fun enhanceJacksonException(fallbackMessage: String, e: Exception): Exception {
-    // These exceptions should only happen if our code is wrong OR if the user is using a binary
-    // incompatible version of `com.fasterxml.jackson.core:jackson-databind`:
-    // https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.18.1/index.html
-    val isUnexpectedException =
-        e is UnrecognizedPropertyException || e is InvalidDefinitionException
-    if (!isUnexpectedException) {
-        return OpenAIInvalidDataException(fallbackMessage, e)
-    }
-
-    val jacksonVersion = JsonMapper::class.java.`package`.implementationVersion
-    if (jacksonVersion.isNullOrEmpty() || jacksonVersion == COMPILED_JACKSON_VERSION) {
-        return OpenAIInvalidDataException(fallbackMessage, e)
-    }
-
-    return OpenAIException(
-        """
-            Jackson threw an unexpected exception and its runtime version ($jacksonVersion) mismatches the version the SDK was compiled with ($COMPILED_JACKSON_VERSION).
-
-            You may be using a version of `com.fasterxml.jackson.core:jackson-databind` that's not binary compatible with the SDK.
-
-            This can happen if you are either:
-            1. Directly depending on a different Jackson version
-            2. Depending on some library that depends on a different Jackson version, potentially transitively
-
-            Double-check that you are depending on a compatible Jackson version.
-        """
-            .trimIndent(),
-        e,
-    )
-}
-
-const val COMPILED_JACKSON_VERSION = "2.18.1"