[aisdk] Updates to openai jsonschema encoding (#586)

## Summary
OpenAI uses
[jsonschema](https://json-schema.org/understanding-json-schema/reference)
to define a function tool's input (and other things), but they don't
support any arbitrary json schema. Here we implement some (but not all)
of the [supported
subset](https://platform.openai.com/docs/guides/structured-outputs#supported-schemas),
and force that schemas always contain `properties`, even if empty. These
were being omitted when empty because the `Schema` struct has
`json:"omitempty"`)

Implementing all the OpenAI restrictions seems like unnecessary eager
validation. The API itself will return an error if an invalid schema is
passed in.

## How was it tested?
Unit tests

## Community Contribution License

All community contributions in this pull request are licensed to the
project maintainers under the terms of the [Apache 2
License](https://www.apache.org/licenses/LICENSE-2.0).

By creating this pull request I represent that I have the right to
license the contributions to the project maintainers under the Apache 2
License as stated in the [Community Contribution
License](https://github.com/jetify-com/opensource/blob/main/CONTRIBUTING.md#community-contribution-license).

Co-authored-by: Rodrigo Ipince <ipince@users.noreply.github.com>

Author: ipince

aisdk/ai/provider/openai/internal/codec/jsonschema.go

@@ -16,6 +16,17 @@ func encodeSchema(schema *jsonschema.Schema) (map[string]any, error) {
 		return nil, nil
 	}
 
+	// Enforce OpenAI restrictions
+	// https://platform.openai.com/docs/guides/structured-outputs#root-objects-must-not-be-anyof-and-must-be-an-object
+	// NOTE: we could simply encode the input schema, pass it through to OpenAI and let it return an error, but there are
+	// other encoding rules we want to enforce later, and limiting the scope here allows us to limit the scope later.
+	if schema.Type != "object" {
+		return nil, fmt.Errorf("schema root must be of type object, got: %s", schema.Type)
+	}
+	if schema.AnyOf != nil {
+		return nil, fmt.Errorf("schema root cannot use AnyOf")
+	}
+
 	// Marshal to JSON and unmarshal back to interface{} to convert the types
 	data, err := json.Marshal(schema)
 	if err != nil {
@@ -32,6 +43,12 @@ func encodeSchema(schema *jsonschema.Schema) (map[string]any, error) {
 		return nil, fmt.Errorf("failed to unmarshal properties: %w\n\n%s", err, data)
 	}
 
+	// Ensure properties field is set, even if it's empty. It's unclear whether OpenAI requires
+	// this to be set for nested schema objects too. For now we only set it at the top-level.
+	if _, ok := result["properties"]; !ok {
+		result["properties"] = map[string]any{}
+	}
+
 	// Convert {"not": {}} patterns to false throughout the schema
 	normalizeSchemaMap(result)
 

aisdk/ai/provider/openai/internal/codec/jsonschema_test.go

@@ -143,20 +143,42 @@ func TestEncodeSchema(t *testing.T) {
 			}`,
 		},
 		{
-			name: "schema with allOf containing additionalProperties",
+			name: "schema with nested AnyOf",
 			input: &jsonschema.Schema{
-				AllOf: []*jsonschema.Schema{
-					{
-						Type:                 "object",
-						AdditionalProperties: api.FalseSchema(),
+				Type: "object",
+				Properties: map[string]*jsonschema.Schema{
+					"numeric": {
+						AnyOf: []*jsonschema.Schema{
+							{
+								Type: "string",
+							},
+							{
+								Type: "number",
+							},
+						},
 					},
 				},
 			},
 			want: `{
-				"allOf": [{
-					"type": "object",
-					"additionalProperties": false
-				}]
+				"type": "object",
+				"properties": {
+					"numeric": {
+						"anyOf": [
+							{ "type": "string" },
+							{ "type": "number" }
+						]
+					}
+				}
+			}`,
+		},
+		{
+			name: "schema without properties gets empty properties map",
+			input: &jsonschema.Schema{
+				Type: "object",
+			},
+			want: `{
+				"type": "object",
+				"properties": {}
 			}`,
 		},
 		{
@@ -210,6 +232,44 @@ func TestEncodeSchema(t *testing.T) {
 				"required": ["id"]
 			}`,
 		},
+
+		// Edge/error cases
+		{
+			name: "schema with non-object root",
+			input: &jsonschema.Schema{
+				Properties: map[string]*jsonschema.Schema{
+					"name": {
+						Type:        "string",
+						Description: "The name",
+					},
+				},
+			},
+			wantErr: true,
+		},
+		{
+			name:    "empty schema",
+			input:   &jsonschema.Schema{},
+			wantErr: true,
+		},
+		{
+			name: "schema with only additional properties",
+			input: &jsonschema.Schema{
+				AdditionalProperties: api.FalseSchema(),
+			},
+			wantErr: true,
+		},
+		{
+			name: "schema with AnyOf at rool level",
+			input: &jsonschema.Schema{
+				AnyOf: []*jsonschema.Schema{
+					{
+						Type:                 "object",
+						AdditionalProperties: api.FalseSchema(),
+					},
+				},
+			},
+			wantErr: true,
+		},
 	}
 
 	for _, tt := range tests {
@@ -451,35 +511,3 @@ func TestNormalizeSchemaMap(t *testing.T) {
 		})
 	}
 }
-
-func TestEncodeSchema_EdgeCases(t *testing.T) {
-	t.Run("schema with only additionalProperties", func(t *testing.T) {
-		schema := &jsonschema.Schema{
-			AdditionalProperties: api.FalseSchema(),
-		}
-
-		got, err := encodeSchema(schema)
-		require.NoError(t, err)
-
-		gotJSON, err := json.Marshal(got)
-		require.NoError(t, err)
-
-		expectedJSON := `{
-			"additionalProperties": false
-		}`
-
-		assert.JSONEq(t, expectedJSON, string(gotJSON))
-	})
-
-	t.Run("empty schema", func(t *testing.T) {
-		schema := &jsonschema.Schema{}
-
-		got, err := encodeSchema(schema)
-		require.NoError(t, err)
-
-		gotJSON, err := json.Marshal(got)
-		require.NoError(t, err)
-
-		assert.JSONEq(t, "{}", string(gotJSON))
-	})
-}