chore(docs): clarify breaking changes (#306)

Author: stainless-app[bot]

Diff for: MIGRATION.md

@@ -2,19 +2,39 @@
 
 <a href="https://pkg.go.dev/github.com/openai/openai-go"><img src="https://pkg.go.dev/badge/github.com/openai/openai-go.svg" alt="Go Reference"></a>
 
-This SDK includes breaking changes from the previous version to improve the ergonomics of constructing parameters and accessing responses.
+This SDK includes breaking changes to improve the ergonomics of constructing parameters and accessing responses.
+
+To reduce verbosity, the `openai.F(...)` and `param.Field[T]` have been removed.
+All calls to `openai.F(...)` can be deleted.
+
+The SDK now uses the <code>\`json:"...,omitzero"\`</code> struct tag to omit fields. Nested structs, arrays and maps
+can be declared like normal.
+
+The old SDK used interfaces for unions in requests, which required
+a type assertion to access variants and fields. The new design uses
+structs with a field for each variant, wherein only one field can be set.
+These struct unions also expose 'Get' methods to access and mutate subfields
+which may be shared by multiple variants.
 
 # Request parameters
 
 ## Required primitives parameters serialize their zero values (`string`, `int64`, etc.)
 
-> [!CAUTION] > **This change can cause new behavior in existing code, without compiler warnings.**
+> [!CAUTION]
+>
+> **This change can cause new behavior in existing code, without compiler warnings.**
+
+While migrating, ensure that all required fields are explicitly set. A required primitive
+field `Age` will use the <code>\`json:"age,required"\`</code> struct tag without `omitzero`.
+
+If a required primitive field is not set, the zero value will be serialized.
+This was not the case in with `param.Field[T]`.
 
 ```diff
 type FooParams struct {
 -        Age  param.Field[int64]  `json:"age,required"`
 -        Name param.Field[string] `json:"name"`
-+        Age  int64               `json:"age,required"`
++        Age  int64               `json:"age,required"` // <== Notice no omitzero
 +        Name param.Opt[string]   `json:"name,omitzero"`
 }
 ```
@@ -48,43 +68,24 @@ _ = FooParams{
 </tr>
 </table>
 
-The required field `"age"` is now present as `0`. Required primitive fields without the <code>\`json:"...,omitzero"\`</code> struct tag
+The required field `"age"` is now present as `0`. Fields without the <code>\`json:"...,omitzero"\`</code> struct tag
 are always serialized, including their zero values.
 
 ## Transition from `param.Field[T]` to `omitzero`
 
-The new SDK uses <a href="https://pkg.go.dev/encoding/json#Marshal"><code>\`json:"...,omitzero"\`</code> semantics</a> from Go 1.24+ for JSON encoding[^1].
-
-`omitzero` is used for structs, slices, maps, string enums, and optional primitive types wrapped in `param.Opt[T]` (e.g. `param.Opt[string]`).
-
-**Fields of a request struct:**
-
-```diff
-type FooParams struct {
--    RequiredString param.Field[string]   `json:"required_string,required"`
-+    RequiredString string                `json:"required_string,required"`
-
--    OptionalString param.Field[string]   `json:"optional_string"`
-+    OptionalString param.Opt[string]     `json:"optional_string,omitzero"`
-
--    Array param.Field[[]BarParam]        `json"array"`
-+    Array []BarParam                     `json"array,omitzero"`
+The `openai.F(...)` function and `param.Field[T]` type are no longer present in the new SDK.
 
--    Map param.Field[map[string]BarParam] `json"map"`
-+    Map map[string]BarParam              `json"map,omitzero"`
+To represent omitted fields, the SDK uses <a href="https://pkg.go.dev/encoding/json#Marshal"><code>\`json:"...,omitzero"\`</code> semantics</a> from Go 1.24+ for JSON encoding[^1]. `omitzero` always omits fields
+with zero values.
 
--    RequiredObject param.Field[BarParam] `json:"required_object,required"`
-+    RequiredObject BarParam              `json:"required_object,omitzero,required"`
+In all cases other than optional primitives, `openai.F()` can simply be removed.
+For optional primitive types, such as `param.Opt[string]`, you can use `openai.String(string)` to construct the value.
+Similar functions exist for other primitive types like `openai.Int(int)`, `openai.Bool(bool)`, etc.
 
--    OptionalObject param.Field[BarParam] `json:"optional_object"`
-+    OptionalObject BarParam              `json:"optional_object,omitzero"`
+`omitzero` is used for fields whose type is either a struct, slice, map, string enum,
+or wrapped optional primitive (e.g. `param.Opt[T]`). Required primitive fields don't use `omitzero`.
 
--    StringEnum     param.Field[BazEnum]  `json:"string_enum"`
-+    StringEnum     BazEnum               `json:"string_enum,omitzero"`
-}
-```
-
-**Previous vs New SDK: Constructing a request**
+**Example User Code: Constructing a request**
 
 ```diff
 foo = FooParams{
@@ -112,12 +113,36 @@ foo = FooParams{
 }
 ```
 
-`param.Opt[string]` can be constructed with `openai.String(string)`. Similar functions exist for other primitive
-types like `openai.Int(int)`, `openai.Bool(bool)`, etc.
+**Internal SDK Code: Fields of a request struct:**
+
+```diff
+type FooParams struct {
+-    RequiredString param.Field[string]   `json:"required_string,required"`
++    RequiredString string                `json:"required_string,required"`
+
+-    OptionalString param.Field[string]   `json:"optional_string"`
++    OptionalString param.Opt[string]     `json:"optional_string,omitzero"`
+
+-    Array param.Field[[]BarParam]        `json"array"`
++    Array []BarParam                     `json"array,omitzero"`
+
+-    Map param.Field[map[string]BarParam] `json"map"`
++    Map map[string]BarParam              `json"map,omitzero"`
+
+-    RequiredObject param.Field[BarParam] `json:"required_object,required"`
++    RequiredObject BarParam              `json:"required_object,omitzero,required"`
+
+-    OptionalObject param.Field[BarParam] `json:"optional_object"`
++    OptionalObject BarParam              `json:"optional_object,omitzero"`
+
+-    StringEnum     param.Field[BazEnum]  `json:"string_enum"`
++    StringEnum     BazEnum               `json:"string_enum,omitzero"`
+}
+```
 
 ## Request Unions: Removing interfaces and moving to structs
 
-For a type `AnimalUnionParam` which could be either a `string | CatParam | DogParam`.
+For a type `AnimalUnionParam` which could be either a `CatParam | DogParam`.
 
 <table>
 <tr><th>Previous</th> <th>New</th></tr>
@@ -237,14 +262,23 @@ The `.IsNull()` method has been changed to `.IsPresent()` to better reflect its
 ```diff
 - if !resp.Foo.JSON.Bar.IsNull() {
 + if resp.Foo.JSON.Bar.IsPresent() {
-     println("bar is present:", resp.Foo.Bar)
-  }
+    println("bar is present:", resp.Foo.Bar)
+}
 ```
 
 | Previous       | New                 | Returns true for values |
 | -------------- | ------------------- | ----------------------- |
 | `.IsNull()`    | `!.IsPresent()`     | `null` or Omitted       |
 | `.IsMissing()` | `.Raw() == ""`      | Omitted                 |
-| `.Invalid()`   | `.IsExplicitNull()` | `null`                  |
+|                | `.IsExplicitNull()` | `null`                  |
+
+## Checking Raw JSON of a response
+
+The `.RawJSON()` method has moved to the parent of the `.JSON` property.
+
+```diff
+- resp.Foo.JSON.RawJSON()
++ resp.Foo.RawJSON()
+```
 
 [^1]: The SDK doesn't require Go 1.24, despite supporting the `omitzero` feature

Diff for: README.md

@@ -5,6 +5,10 @@
 The OpenAI Go library provides convenient access to [the OpenAI REST
 API](https://platform.openai.com/docs) from applications written in Go. The full API of this library can be found in [api.md](api.md).
 
+> [!WARNING]
+> The latest version of this package uses a new design with significant breaking changes.
+> Please refer to the [migration guide](./MIGRATION.md) for more information on how to update your code.
+
 ## Installation
 
 <!-- x-release-please-start-version -->
@@ -342,8 +346,8 @@ Otherwise, the `param.IsOmitted(any)` function can confirm the presence of any `
 Unions are represented as a struct with fields prefixed by "Of" for each of it's variants,
 only one field can be non-zero. The non-zero field will be serialized.
 
-Properties can be accessed via getters on the union struct. These getters return a mutable
-pointer to the underlying data, if present.
+Sub-properties of the union can be accessed via methods on the union struct.
+These methods return a mutable pointer to the underlying data, if present.
 
 ```go
 // Only one field can be non-zero, use param.IsOmitted() to check if a field is set