feat(ai): Add support for minItems and maxItems to Schema

.changeset/angry-scissors-sit.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/ai': minor
+---
+
+Add support for `minItems` and `maxItems` to `Schema`.

common/api-review/ai.api.md

@@ -790,6 +790,9 @@ export abstract class Schema implements SchemaInterface {
     format?: string;
     // (undocumented)
     static integer(integerParams?: SchemaParams): IntegerSchema;
+    items?: SchemaInterface;
+    maxItems?: number;
+    minItems?: number;
     nullable: boolean;
     // (undocumented)
     static number(numberParams?: SchemaParams): NumberSchema;
@@ -831,6 +834,8 @@ export interface SchemaShared<T> {
     example?: unknown;
     format?: string;
     items?: T;
+    maxItems?: number;
+    minItems?: number;
     nullable?: boolean;
     properties?: {
         [k: string]: T;

docs-devsite/ai.schema.md

@@ -32,6 +32,9 @@ export declare abstract class Schema implements SchemaInterface
 |  [description](./ai.schema.md#schemadescription) |  | string | Optional. The description of the property. |
 |  [example](./ai.schema.md#schemaexample) |  | unknown | Optional. The example of the property. |
 |  [format](./ai.schema.md#schemaformat) |  | string | Optional. The format of the property. Supported formats:<br/> <ul> <li>for NUMBER type: "float", "double"</li> <li>for INTEGER type: "int32", "int64"</li> <li>for STRING type: "email", "byte", etc</li> </ul> |
+|  [items](./ai.schema.md#schemaitems) |  | [SchemaInterface](./ai.schemainterface.md#schemainterface_interface) | Optional. The items of the property. |
+|  [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)<!-- -->. |
 
@@ -93,6 +96,36 @@ Optional. The format of the property. Supported formats:<br/> <ul> <li>for NUMBE
 format?: string;
 ```
 
+## Schema.items
+
+Optional. The items of the property.
+
+<b>Signature:</b>
+
+```typescript
+items?: SchemaInterface;
+```
+
+## Schema.maxItems
+
+The maximum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+maxItems?: number;
+```
+
+## Schema.minItems
+
+The minimum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+minItems?: number;
+```
+
 ## Schema.nullable
 
 Optional. Whether the property is nullable. Defaults to false.

docs-devsite/ai.schemashared.md

@@ -27,6 +27,8 @@ export interface SchemaShared<T>
 |  [example](./ai.schemashared.md#schemasharedexample) | unknown | Optional. The example of the property. |
 |  [format](./ai.schemashared.md#schemasharedformat) | string | Optional. The format of the property. When using the Gemini Developer API ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class)<!-- -->), this must be either <code>'enum'</code> or <code>'date-time'</code>, otherwise requests will fail. |
 |  [items](./ai.schemashared.md#schemashareditems) | T | Optional. The items of the property. |
+|  [maxItems](./ai.schemashared.md#schemasharedmaxitems) | number | The maximum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->. |
+|  [minItems](./ai.schemashared.md#schemasharedminitems) | number | The minimum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->. |
 |  [nullable](./ai.schemashared.md#schemasharednullable) | boolean | Optional. Whether the property is nullable. |
 |  [properties](./ai.schemashared.md#schemasharedproperties) | { \[k: string\]: T; } | Optional. Map of <code>Schema</code> objects. |
 
@@ -80,6 +82,26 @@ Optional. The items of the property.
 items?: T;
 ```
 
+## SchemaShared.maxItems
+
+The maximum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+maxItems?: number;
+```
+
+## SchemaShared.minItems
+
+The minimum number of items (elements) in a schema of type [SchemaType.ARRAY](./ai.md#schematypearray_enummember)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+minItems?: number;
+```
+
 ## SchemaShared.nullable
 
 Optional. Whether the property is nullable.

packages/ai/src/requests/schema-builder.test.ts

@@ -81,6 +81,93 @@ describe('Schema builder', () => {
       nullable: false
     });
   });
+  describe('Schema.array', () => {
+    it('builds an array schema with basic items', () => {
+      const schema = Schema.array({
+        items: Schema.string()
+      });
+      expect(schema.toJSON()).to.eql({
+        type: 'array',
+        nullable: false,
+        items: {
+          type: 'string',
+          nullable: false
+        }
+      });
+    });
+
+    it('builds an array schema with items and minItems', () => {
+      const schema = Schema.array({
+        items: Schema.number(),
+        minItems: 1
+      });
+      expect(schema.toJSON()).to.eql({
+        type: 'array',
+        nullable: false,
+        items: {
+          type: 'number',
+          nullable: false
+        },
+        minItems: 1
+      });
+    });
+
+    it('builds an array schema with items and maxItems', () => {
+      const schema = Schema.array({
+        items: Schema.boolean(),
+        maxItems: 10
+      });
+      expect(schema.toJSON()).to.eql({
+        type: 'array',
+        nullable: false,
+        items: {
+          type: 'boolean',
+          nullable: false
+        },
+        maxItems: 10
+      });
+    });
+
+    it('builds an array schema with items, minItems, and maxItems', () => {
+      const schema = Schema.array({
+        items: Schema.integer(),
+        minItems: 0,
+        maxItems: 5
+      });
+      expect(schema.toJSON()).to.eql({
+        type: 'array',
+        nullable: false,
+        items: {
+          type: 'integer',
+          nullable: false
+        },
+        minItems: 0,
+        maxItems: 5
+      });
+    });
+
+    it('builds an array schema with items, minItems, maxItems, and other options', () => {
+      const schema = Schema.array({
+        items: Schema.string({ description: 'A list of names' }),
+        minItems: 1,
+        maxItems: 3,
+        nullable: true,
+        description: 'An array of strings'
+      });
+      expect(schema.toJSON()).to.eql({
+        type: 'array',
+        nullable: true,
+        description: 'An array of strings',
+        items: {
+          type: 'string',
+          description: 'A list of names',
+          nullable: false
+        },
+        minItems: 1,
+        maxItems: 3
+      });
+    });
+  });
   it('builds an object schema', () => {
     const schema = Schema.object({
       properties: {

packages/ai/src/requests/schema-builder.ts

@@ -49,6 +49,12 @@ export abstract class Schema implements SchemaInterface {
   format?: string;
   /** Optional. The description of the property. */
   description?: string;
+  /** Optional. The items of the property. */
+  items?: SchemaInterface;
+  /** The minimum number of items (elements) in a schema of type {@link SchemaType.ARRAY}. */
+  minItems?: number;
+  /** The maximum number of items (elements) in a schema of type {@link SchemaType.ARRAY}. */
+  maxItems?: number;
   /** Optional. Whether the property is nullable. Defaults to false. */
   nullable: boolean;
   /** Optional. The example of the property. */

packages/ai/src/types/schema.ts

@@ -51,6 +51,10 @@ export interface SchemaShared<T> {
   description?: string;
   /** Optional. The items of the property. */
   items?: T;
+  /** The minimum number of items (elements) in a schema of type {@link SchemaType.ARRAY}. */
+  minItems?: number;
+  /** The maximum number of items (elements) in a schema of type {@link SchemaType.ARRAY}. */
+  maxItems?: number;
   /** Optional. Map of `Schema` objects. */
   properties?: {
     [k: string]: T;