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

Author: dlarocque

.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;

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. */
@@ -77,7 +83,7 @@ export abstract class Schema implements SchemaInterface {
    * @internal
    */
   toJSON(): SchemaRequest {
-    const obj: { type: SchemaType; [key: string]: unknown } = {
+    const obj: { type: SchemaType;[key: string]: unknown } = {
       type: this.type
     };
     for (const prop in this) {

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;
@@ -69,7 +73,7 @@ export interface SchemaShared<T> {
  * {@link Schema} classes.
  * @public
  */
-export interface SchemaParams extends SchemaShared<SchemaInterface> {}
+export interface SchemaParams extends SchemaShared<SchemaInterface> { }
 
 /**
  * Final format for {@link Schema} params passed to backend requests.