@ai-sdk/google 4.0.47 → 4.0.48

package/docs/15-google.mdx

@@ -1467,7 +1467,7 @@ Function tools work the same way as on the standard provider:
 
 ```ts
 import { google } from '@ai-sdk/google';
-import { generateText, stepCountIs, tool } from 'ai';
+import { generateText, isStepCount, tool } from 'ai';
 import { z } from 'zod';
 
 const weatherTool = tool({
@@ -1479,7 +1479,7 @@ const weatherTool = tool({
 const { text, toolCalls } = await generateText({
   model: google.interactions('gemini-3.7-flash'),
   tools: { getWeather: weatherTool },
-  stopWhen: stepCountIs(5),
+  stopWhen: isStepCount(5),
   prompt: 'What is the weather in San Francisco right now?',
 });
 ```
@@ -1804,7 +1804,7 @@ import { generateText } from 'ai';
 
 const { text } = await generateText({
   model: google('gemma-3-27b-it'),
-  system: 'You are a helpful assistant that responds concisely.',
+  instructions: 'You are a helpful assistant that responds concisely.',
   prompt: 'What is machine learning?',
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/google",
-  "version": "4.0.47",
+  "version": "4.0.48",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/convert-json-schema-to-openapi-schema.ts

@@ -4,6 +4,16 @@ import {
   type JSONSchema7Definition,
 } from '@ai-sdk/provider';
 
+type JSONSchema7WithDefinitions = JSONSchema7 & {
+  $defs?: Record<string, JSONSchema7Definition>;
+};
+
+type ReferenceContext = {
+  definitions: Record<string, JSONSchema7Definition> | undefined;
+  dollarDefinitions: Record<string, JSONSchema7Definition> | undefined;
+  resolvingReferences: ReadonlySet<string>;
+};
+
 /**
  * Converts JSON Schema 7 to OpenAPI Schema 3.0
  */
@@ -11,26 +21,52 @@ export function convertJSONSchemaToOpenAPISchema(
   jsonSchema: JSONSchema7Definition | undefined,
   isRoot = true,
 ): unknown {
-  // Handle empty object schemas: undefined at root, preserved when nested
+  const rootSchema =
+    typeof jsonSchema === 'object'
+      ? (jsonSchema as JSONSchema7WithDefinitions)
+      : undefined;
+
+  return convertJSONSchemaDefinition(jsonSchema, isRoot, {
+    definitions: rootSchema?.definitions,
+    dollarDefinitions: rootSchema?.$defs,
+    resolvingReferences: new Set(),
+  });
+}
+
+function convertJSONSchemaDefinition(
+  jsonSchema: JSONSchema7Definition | undefined,
+  isRoot: boolean,
+  referenceContext: ReferenceContext,
+): unknown {
   if (jsonSchema == null) {
     return undefined;
   }
 
+  if (typeof jsonSchema === 'boolean') {
+    return { type: 'boolean', properties: {} };
+  }
+
+  if (jsonSchema.$ref != null) {
+    return convertJSONSchemaReference({
+      jsonSchema,
+      reference: jsonSchema.$ref,
+      isRoot,
+      referenceContext,
+    });
+  }
+
+  // Handle empty object schemas: undefined at root, preserved when nested
   if (isEmptyObjectSchema(jsonSchema)) {
     if (isRoot) {
       return undefined;
     }
 
-    if (typeof jsonSchema === 'object' && jsonSchema.description) {
+    if (jsonSchema.description) {
       return { type: 'object', description: jsonSchema.description };
     }
     return { type: 'object' };
   }
 
-  if (typeof jsonSchema === 'boolean') {
-    return { type: 'boolean', properties: {} };
-  }
-
   const {
     type,
     description,
@@ -83,7 +119,7 @@ export function convertJSONSchemaToOpenAPISchema(
   if (properties != null) {
     result.properties = Object.entries(properties).reduce(
       (acc, [key, value]) => {
-        acc[key] = convertJSONSchemaToOpenAPISchema(value, false);
+        acc[key] = convertJSONSchemaDefinition(value, false, referenceContext);
         return acc;
       },
       {} as Record<string, unknown>,
@@ -92,13 +128,15 @@ export function convertJSONSchemaToOpenAPISchema(
 
   if (items) {
     result.items = Array.isArray(items)
-      ? items.map(item => convertJSONSchemaToOpenAPISchema(item, false))
-      : convertJSONSchemaToOpenAPISchema(items, false);
+      ? items.map(item =>
+          convertJSONSchemaDefinition(item, false, referenceContext),
+        )
+      : convertJSONSchemaDefinition(items, false, referenceContext);
   }
 
   if (allOf) {
     result.allOf = allOf.map(item =>
-      convertJSONSchemaToOpenAPISchema(item, false),
+      convertJSONSchemaDefinition(item, false, referenceContext),
     );
   }
   if (anyOf) {
@@ -114,9 +152,10 @@ export function convertJSONSchemaToOpenAPISchema(
 
       if (nonNullSchemas.length === 1) {
         // If there's only one non-null schema, convert it and make it nullable
-        const converted = convertJSONSchemaToOpenAPISchema(
+        const converted = convertJSONSchemaDefinition(
           nonNullSchemas[0],
           false,
+          referenceContext,
         );
         if (typeof converted === 'object') {
           result.nullable = true;
@@ -125,19 +164,19 @@ export function convertJSONSchemaToOpenAPISchema(
       } else {
         // If there are multiple non-null schemas, keep them in anyOf
         result.anyOf = nonNullSchemas.map(item =>
-          convertJSONSchemaToOpenAPISchema(item, false),
+          convertJSONSchemaDefinition(item, false, referenceContext),
         );
         result.nullable = true;
       }
     } else {
       result.anyOf = anyOf.map(item =>
-        convertJSONSchemaToOpenAPISchema(item, false),
+        convertJSONSchemaDefinition(item, false, referenceContext),
       );
     }
   }
   if (oneOf) {
     result.oneOf = oneOf.map(item =>
-      convertJSONSchemaToOpenAPISchema(item, false),
+      convertJSONSchemaDefinition(item, false, referenceContext),
     );
   }
 
@@ -148,6 +187,124 @@ export function convertJSONSchemaToOpenAPISchema(
   return result;
 }
 
+function convertJSONSchemaReference({
+  jsonSchema,
+  reference,
+  isRoot,
+  referenceContext,
+}: {
+  jsonSchema: JSONSchema7;
+  reference: string;
+  isRoot: boolean;
+  referenceContext: ReferenceContext;
+}): unknown {
+  const { definition, referenceKey } = getReferencedDefinition(
+    reference,
+    referenceContext,
+  );
+
+  if (referenceContext.resolvingReferences.has(referenceKey)) {
+    throw new UnsupportedFunctionalityError({
+      functionality: `recursive JSON Schema reference: ${reference}`,
+      message:
+        'Google schema conversion does not support recursive JSON Schema references.',
+    });
+  }
+
+  const resolvingReferences = new Set(referenceContext.resolvingReferences);
+  resolvingReferences.add(referenceKey);
+
+  // Inline references instead of emitting Google's `ref` / `defs` fields.
+  // Those fields are supported by Vertex AI's Schema representation but are
+  // rejected by the Gemini Developer API representation used by this shared
+  // converter.
+  const { $ref: _reference, ...siblingSchema } = jsonSchema;
+  const resolvedSchema =
+    typeof definition === 'boolean'
+      ? definition
+        ? siblingSchema
+        : false
+      : { ...definition, ...siblingSchema };
+
+  return convertJSONSchemaDefinition(resolvedSchema, isRoot, {
+    ...referenceContext,
+    resolvingReferences,
+  });
+}
+
+function getReferencedDefinition(
+  reference: string,
+  referenceContext: ReferenceContext,
+): {
+  definition: JSONSchema7Definition;
+  referenceKey: string;
+} {
+  const definitionSources = [
+    {
+      prefix: '#/$defs/',
+      definitions: referenceContext.dollarDefinitions,
+    },
+    {
+      prefix: '#/definitions/',
+      definitions: referenceContext.definitions,
+    },
+  ];
+
+  const source = definitionSources.find(({ prefix }) =>
+    reference.startsWith(prefix),
+  );
+  const encodedDefinitionName = source
+    ? reference.slice(source.prefix.length)
+    : undefined;
+
+  if (
+    source == null ||
+    encodedDefinitionName == null ||
+    encodedDefinitionName.length === 0 ||
+    encodedDefinitionName.includes('/')
+  ) {
+    throwUnsupportedReference(reference);
+  }
+
+  let decodedDefinitionName: string;
+  try {
+    decodedDefinitionName = decodeURIComponent(encodedDefinitionName);
+  } catch {
+    throwUnsupportedReference(reference);
+  }
+
+  if (
+    decodedDefinitionName.includes('/') ||
+    /~(?![01])/u.test(decodedDefinitionName) ||
+    source.definitions == null
+  ) {
+    throwUnsupportedReference(reference);
+  }
+
+  const definitionName = decodedDefinitionName.replace(/~[01]/g, match =>
+    match === '~1' ? '/' : '~',
+  );
+
+  if (
+    !Object.prototype.hasOwnProperty.call(source.definitions, definitionName)
+  ) {
+    throwUnsupportedReference(reference);
+  }
+
+  return {
+    definition: source.definitions[definitionName],
+    referenceKey: `${source.prefix}${definitionName}`,
+  };
+}
+
+function throwUnsupportedReference(reference: string): never {
+  throw new UnsupportedFunctionalityError({
+    functionality: `JSON Schema reference: ${reference}`,
+    message:
+      'Google schema conversion only supports references to direct children of root-level $defs or definitions.',
+  });
+}
+
 type EnumValues = NonNullable<JSONSchema7['enum']>;
 type EnumType = 'string' | 'number' | 'integer' | 'boolean';
 type GoogleEnumSchema = {