feat!(ai): add support for anyOf schemas

.changeset/healthy-moons-type.md

@@ -0,0 +1,6 @@
+---
+'firebase': major
+'@firebase/ai': major
+---
+
+Add support for `anyOf` schemas

common/api-review/ai.api.md

@@ -65,6 +65,17 @@ export interface AIOptions {
     backend: Backend;
 }
 
+// @public
+export class AnyOfSchema extends Schema {
+    constructor(schemaParams: SchemaParams & {
+        anyOf: TypedSchema[];
+    });
+    // (undocumented)
+    anyOf: TypedSchema[];
+    // @internal (undocumented)
+    toJSON(): SchemaRequest;
+}
+
 // @public
 export class ArraySchema extends Schema {
     constructor(schemaParams: SchemaParams, items: TypedSchema);
@@ -777,6 +788,10 @@ export abstract class Schema implements SchemaInterface {
     constructor(schemaParams: SchemaInterface);
     [key: string]: unknown;
     // (undocumented)
+    static anyOf(anyOfParams: SchemaParams & {
+        anyOf: TypedSchema[];
+    }): AnyOfSchema;
+    // (undocumented)
     static array(arrayParams: SchemaParams & {
         items: Schema;
     }): ArraySchema;
@@ -808,12 +823,12 @@ export abstract class Schema implements SchemaInterface {
     static string(stringParams?: SchemaParams): StringSchema;
     // @internal
     toJSON(): SchemaRequest;
-    type: SchemaType;
+    type?: SchemaType;
 }
 
 // @public
 export interface SchemaInterface extends SchemaShared<SchemaInterface> {
-    type: SchemaType;
+    type?: SchemaType;
 }
 
 // @public
@@ -823,13 +838,14 @@ export interface SchemaParams extends SchemaShared<SchemaInterface> {
 // @public
 export interface SchemaRequest extends SchemaShared<SchemaRequest> {
     required?: string[];
-    type: SchemaType;
+    type?: SchemaType;
 }
 
 // @public
 export interface SchemaShared<T> {
     // (undocumented)
     [key: string]: unknown;
+    anyOf?: T[];
     description?: string;
     enum?: string[];
     example?: unknown;
@@ -910,7 +926,7 @@ export interface ToolConfig {
 }
 
 // @public
-export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema;
+export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 
 // @public
 export interface UsageMetadata {

docs-devsite/_toc.yaml

@@ -12,6 +12,8 @@ toc:
     path: /docs/reference/js/ai.aimodel.md
   - title: AIOptions
     path: /docs/reference/js/ai.aioptions.md
+  - title: AnyOfSchema
+    path: /docs/reference/js/ai.anyofschema.md
   - title: ArraySchema
     path: /docs/reference/js/ai.arrayschema.md
   - title: Backend

docs-devsite/ai.anyofschema.md

@@ -0,0 +1,58 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# AnyOfSchema class
+Schema class representing a value that can conform to any of the provided sub-schemas. This is useful when a field can accept multiple distinct types or structures.
+
+<b>Signature:</b>
+
+```typescript
+export declare class AnyOfSchema extends Schema 
+```
+<b>Extends:</b> [Schema](./ai.schema.md#schema_class)
+
+## Constructors
+
+|  Constructor | Modifiers | Description |
+|  --- | --- | --- |
+|  [(constructor)(schemaParams)](./ai.anyofschema.md#anyofschemaconstructor) |  | Constructs a new instance of the <code>AnyOfSchema</code> class |
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [anyOf](./ai.anyofschema.md#anyofschemaanyof) |  | [TypedSchema](./ai.md#typedschema)<!-- -->\[\] |  |
+
+## AnyOfSchema.(constructor)
+
+Constructs a new instance of the `AnyOfSchema` class
+
+<b>Signature:</b>
+
+```typescript
+constructor(schemaParams: SchemaParams & {
+        anyOf: TypedSchema[];
+    });
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  schemaParams | [SchemaParams](./ai.schemaparams.md#schemaparams_interface) &amp; { anyOf: [TypedSchema](./ai.md#typedschema)<!-- -->\[\]; } |  |
+
+## AnyOfSchema.anyOf
+
+<b>Signature:</b>
+
+```typescript
+anyOf: TypedSchema[];
+```

docs-devsite/ai.generationconfig.md

@@ -28,7 +28,7 @@ export interface GenerationConfig
 |  [presencePenalty](./ai.generationconfig.md#generationconfigpresencepenalty) | number |  |
 |  [responseMimeType](./ai.generationconfig.md#generationconfigresponsemimetype) | string | Output response MIME type of the generated candidate text. Supported MIME types are <code>text/plain</code> (default, text output), <code>application/json</code> (JSON response in the candidates), and <code>text/x.enum</code>. |
 |  [responseModalities](./ai.generationconfig.md#generationconfigresponsemodalities) | [ResponseModality](./ai.md#responsemodality)<!-- -->\[\] | <b><i>(Public Preview)</i></b> Generation modalities to be returned in generation responses. |
-|  [responseSchema](./ai.generationconfig.md#generationconfigresponseschema) | [TypedSchema](./ai.md#typedschema) \| [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) | Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./ai.schema.md#schema_class) static method like <code>Schema.string()</code> or <code>Schema.object()</code> or it can be a plain JS object matching the [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) interface. <br/>Note: This only applies when the specified <code>responseMIMEType</code> supports a schema; currently this is limited to <code>application/json</code> and <code>text/x.enum</code>. |
+|  [responseSchema](./ai.generationconfig.md#generationconfigresponseschema) | [TypedSchema](./ai.md#typedschema) \| [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) | Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./ai.schema.md#schema_class) static method like <code>Schema.string()</code> or <code>Schema.object()</code> or it can be a plain JS object matching the [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) interface. <br/>Note: This only applies when the specified <code>responseMimeType</code> supports a schema; currently this is limited to <code>application/json</code> and <code>text/x.enum</code>. |
 |  [stopSequences](./ai.generationconfig.md#generationconfigstopsequences) | string\[\] |  |
 |  [temperature](./ai.generationconfig.md#generationconfigtemperature) | number |  |
 |  [topK](./ai.generationconfig.md#generationconfigtopk) | number |  |
@@ -93,7 +93,7 @@ responseModalities?: ResponseModality[];
 
 ## GenerationConfig.responseSchema
 
-Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./ai.schema.md#schema_class) static method like `Schema.string()` or `Schema.object()` or it can be a plain JS object matching the [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) interface. <br/>Note: This only applies when the specified `responseMIMEType` supports a schema; currently this is limited to `application/json` and `text/x.enum`<!-- -->.
+Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./ai.schema.md#schema_class) static method like `Schema.string()` or `Schema.object()` or it can be a plain JS object matching the [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) interface. <br/>Note: This only applies when the specified `responseMimeType` supports a schema; currently this is limited to `application/json` and `text/x.enum`<!-- -->.
 
 <b>Signature:</b>
 

docs-devsite/ai.md

@@ -29,6 +29,7 @@ The Firebase AI Web SDK.
 |  --- | --- |
 |  [AIError](./ai.aierror.md#aierror_class) | Error class for the Firebase AI SDK. |
 |  [AIModel](./ai.aimodel.md#aimodel_class) | Base class for Firebase AI model APIs.<!-- -->Instances of this class are associated with a specific Firebase AI [Backend](./ai.backend.md#backend_class) and provide methods for interacting with the configured generative model. |
+|  [AnyOfSchema](./ai.anyofschema.md#anyofschema_class) | Schema class representing a value that can conform to any of the provided sub-schemas. This is useful when a field can accept multiple distinct types or structures. |
 |  [ArraySchema](./ai.arrayschema.md#arrayschema_class) | Schema class for "array" types. The <code>items</code> param should refer to the type of item that can be a member of the array. |
 |  [Backend](./ai.backend.md#backend_class) | Abstract base class representing the configuration for an AI service backend. This class should not be instantiated directly. Use its subclasses; [GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class) for the Gemini Developer API (via [Google AI](https://ai.google/)<!-- -->), and [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class) for the Vertex AI Gemini API. |
 |  [BooleanSchema](./ai.booleanschema.md#booleanschema_class) | Schema class for "boolean" types. |
@@ -410,7 +411,7 @@ A type that includes all specific Schema types.
 <b>Signature:</b>
 
 ```typescript
-export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema;
+export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 ```
 
 ## VertexAI

docs-devsite/ai.schema.md

@@ -36,12 +36,13 @@ export declare abstract class Schema implements SchemaInterface
 |  [maxItems](./ai.schema.md#schemamaxitems) |  | number | The maximum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->. |
 |  [minItems](./ai.schema.md#schemaminitems) |  | number | The minimum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->. |
 |  [nullable](./ai.schema.md#schemanullable) |  | boolean | Optional. Whether the property is nullable. Defaults to false. |
-|  [type](./ai.schema.md#schematype) |  | [SchemaType](./ai.md#schematype) | Optional. The type of the property. [SchemaType](./ai.md#schematype)<!-- -->. |
+|  [type](./ai.schema.md#schematype) |  | [SchemaType](./ai.md#schematype) | Optional. The type of the property. [SchemaType](./ai.md#schematype)<!-- -->. This can only be undefined when using <code>anyOf</code> schemas, which do not have an explicit type in the [OpenAPI specification](https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type)<!-- -->. |
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
+|  [anyOf(anyOfParams)](./ai.schema.md#schemaanyof) | <code>static</code> |  |
 |  [array(arrayParams)](./ai.schema.md#schemaarray) | <code>static</code> |  |
 |  [boolean(booleanParams)](./ai.schema.md#schemaboolean) | <code>static</code> |  |
 |  [enumString(stringParams)](./ai.schema.md#schemaenumstring) | <code>static</code> |  |
@@ -138,14 +139,34 @@ nullable: boolean;
 
 ## Schema.type
 
-Optional. The type of the property. [SchemaType](./ai.md#schematype)<!-- -->.
+Optional. The type of the property. [SchemaType](./ai.md#schematype)<!-- -->. This can only be undefined when using `anyOf` schemas, which do not have an explicit type in the [OpenAPI specification](https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type)<!-- -->.
 
 <b>Signature:</b>
 
 ```typescript
-type: SchemaType;
+type?: SchemaType;
 ```
 
+## Schema.anyOf()
+
+<b>Signature:</b>
+
+```typescript
+static anyOf(anyOfParams: SchemaParams & {
+        anyOf: TypedSchema[];
+    }): AnyOfSchema;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  anyOfParams | [SchemaParams](./ai.schemaparams.md#schemaparams_interface) &amp; { anyOf: [TypedSchema](./ai.md#typedschema)<!-- -->\[\]; } |  |
+
+<b>Returns:</b>
+
+[AnyOfSchema](./ai.anyofschema.md#anyofschema_class)
+
 ## Schema.array()
 
 <b>Signature:</b>

docs-devsite/ai.schemainterface.md

@@ -23,14 +23,14 @@ export interface SchemaInterface extends SchemaShared<SchemaInterface>
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [type](./ai.schemainterface.md#schemainterfacetype) | [SchemaType](./ai.md#schematype) | The type of the property. [SchemaType](./ai.md#schematype)<!-- -->. |
+|  [type](./ai.schemainterface.md#schemainterfacetype) | [SchemaType](./ai.md#schematype) | The type of the property. this can only be undefined when using <code>anyof</code> schemas, which do not have an explicit type in the [OpenAPI Specification](https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type)<!-- -->. |
 
 ## SchemaInterface.type
 
-The type of the property. [SchemaType](./ai.md#schematype)<!-- -->.
+The type of the property. this can only be undefined when using `anyof` schemas, which do not have an explicit type in the [OpenAPI Specification](https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type)<!-- -->.
 
 <b>Signature:</b>
 
 ```typescript
-type: SchemaType;
+type?: SchemaType;
 ```

docs-devsite/ai.schemarequest.md

@@ -24,7 +24,7 @@ export interface SchemaRequest extends SchemaShared<SchemaRequest>
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [required](./ai.schemarequest.md#schemarequestrequired) | string\[\] | Optional. Array of required property. |
-|  [type](./ai.schemarequest.md#schemarequesttype) | [SchemaType](./ai.md#schematype) | The type of the property. [SchemaType](./ai.md#schematype)<!-- -->. |
+|  [type](./ai.schemarequest.md#schemarequesttype) | [SchemaType](./ai.md#schematype) | The type of the property. this can only be undefined when using <code>anyOf</code> schemas, which do not have an explicit type in the [OpenAPI specification](https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type)<!-- -->. |
 
 ## SchemaRequest.required
 
@@ -38,10 +38,10 @@ required?: string[];
 
 ## SchemaRequest.type
 
-The type of the property. [SchemaType](./ai.md#schematype)<!-- -->.
+The type of the property. this can only be undefined when using `anyOf` schemas, which do not have an explicit type in the [OpenAPI specification](https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type)<!-- -->.
 
 <b>Signature:</b>
 
 ```typescript
-type: SchemaType;
+type?: SchemaType;
 ```

docs-devsite/ai.schemashared.md

@@ -22,6 +22,7 @@ export interface SchemaShared<T>
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [anyOf](./ai.schemashared.md#schemasharedanyof) | T\[\] | An array of [Schema](./ai.schema.md#schema_class)<!-- -->. The generated data must be valid against any of the schemas listed in this array. This allows specifying multiple possible structures or types for a single field. |
 |  [description](./ai.schemashared.md#schemashareddescription) | string | Optional. The description of the property. |
 |  [enum](./ai.schemashared.md#schemasharedenum) | string\[\] | Optional. The enum of the property. |
 |  [example](./ai.schemashared.md#schemasharedexample) | unknown | Optional. The example of the property. |
@@ -36,6 +37,16 @@ export interface SchemaShared<T>
 |  [propertyOrdering](./ai.schemashared.md#schemasharedpropertyordering) | string\[\] | A hint suggesting the order in which the keys should appear in the generated JSON string. |
 |  [title](./ai.schemashared.md#schemasharedtitle) | string | The title of the property. This helps document the schema's purpose but does not typically constrain the generated value. It can subtly guide the model by clarifying the intent of a field. |
 
+## SchemaShared.anyOf
+
+An array of [Schema](./ai.schema.md#schema_class)<!-- -->. The generated data must be valid against any of the schemas listed in this array. This allows specifying multiple possible structures or types for a single field.
+
+<b>Signature:</b>
+
+```typescript
+anyOf?: T[];
+```
+
 ## SchemaShared.description
 
 Optional. The description of the property.