From e0c1042301227ff46053ea39f41a3ea7e09b4a57 Mon Sep 17 00:00:00 2001
From: Stainless Bot <dev@stainless.com>
Date: Sun, 9 Mar 2025 22:20:15 +0000
Subject: [PATCH] docs: document `JsonValue` construction in readme

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0684858e..ca270570 100644
--- a/README.md
+++ b/README.md
@@ -302,7 +302,7 @@ FileCreateParams params = FileCreateParams.builder()
 FileObject fileObject = client.files().create(params);
 ```
 
-Note that when passing a non-`Path` its filename is unknown so it will not be included in the request. To manually set a filename, pass a `MultipartField`:
+Note that when passing a non-`Path` its filename is unknown so it will not be included in the request. To manually set a filename, pass a [`MultipartField`](openai-java-core/src/main/kotlin/com/openai/core/Values.kt):
 
 ```java
 import com.openai.core.MultipartField;
@@ -608,7 +608,7 @@ ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
 
 These properties can be accessed on the nested built object later using the `_additionalProperties()` method.
 
-To set a documented parameter or property to an undocumented or not yet supported _value_, pass a [`JsonValue`](openai-java-core/src/main/kotlin/com/openai/core/JsonValue.kt) object to its setter:
+To set a documented parameter or property to an undocumented or not yet supported _value_, pass a [`JsonValue`](openai-java-core/src/main/kotlin/com/openai/core/Values.kt) object to its setter:
 
 ```java
 import com.openai.core.JsonValue;
@@ -620,6 +620,45 @@ ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
     .build();
 ```
 
+The most straightforward way to create a [`JsonValue`](openai-java-core/src/main/kotlin/com/openai/core/Values.kt) is using its `from(...)` method:
+
+```java
+import com.openai.core.JsonValue;
+import java.util.List;
+import java.util.Map;
+
+// Create primitive JSON values
+JsonValue nullValue = JsonValue.from(null);
+JsonValue booleanValue = JsonValue.from(true);
+JsonValue numberValue = JsonValue.from(42);
+JsonValue stringValue = JsonValue.from("Hello World!");
+
+// Create a JSON array value equivalent to `["Hello", "World"]`
+JsonValue arrayValue = JsonValue.from(List.of(
+  "Hello", "World"
+));
+
+// Create a JSON object value equivalent to `{ "a": 1, "b": 2 }`
+JsonValue objectValue = JsonValue.from(Map.of(
+  "a", 1,
+  "b", 2
+));
+
+// Create an arbitrarily nested JSON equivalent to:
+// {
+//   "a": [1, 2],
+//   "b": [3, 4]
+// }
+JsonValue complexValue = JsonValue.from(Map.of(
+  "a", List.of(
+    1, 2
+  ),
+  "b", List.of(
+    3, 4
+  )
+));
+```
+
 ### Response properties
 
 To access undocumented response properties, call the `_additionalProperties()` method: