Adds types which will enforce format rules when using String Schemas

.changeset/silly-coats-lie.md

@@ -0,0 +1,5 @@
+---
+"@google/generative-ai": minor
+---
+
+BREAKING CHANGE: Enforce format safety when using string schemas

common/api-review/generative-ai-server.api.md

@@ -129,6 +129,17 @@ export interface Content {
     role: string;
 }
 
+// Warning: (ae-incompatible-release-tags) The symbol "EnumStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
+//
+// @public
+export interface EnumStringSchema extends BaseSchema {
+    enum: string[];
+    // (undocumented)
+    format: "enum";
+    // (undocumented)
+    type: typeof SchemaType.STRING;
+}
+
 // @public
 export interface ErrorDetails {
     // (undocumented)
@@ -491,19 +502,25 @@ export enum SchemaType {
     STRING = "string"
 }
 
+// Warning: (ae-incompatible-release-tags) The symbol "SimpleStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
+//
+// @public
+export interface SimpleStringSchema extends BaseSchema {
+    // (undocumented)
+    enum?: never;
+    // (undocumented)
+    format?: "date-time" | undefined;
+    // (undocumented)
+    type: typeof SchemaType.STRING;
+}
+
 // @public
 export interface SingleRequestOptions extends RequestOptions {
     signal?: AbortSignal;
 }
 
-// Warning: (ae-incompatible-release-tags) The symbol "StringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
-//
 // @public
-export interface StringSchema extends BaseSchema {
-    enum?: string[];
-    // (undocumented)
-    type: typeof SchemaType.STRING;
-}
+export type StringSchema = SimpleStringSchema | EnumStringSchema;
 
 // @public
 export interface TextPart {

common/api-review/generative-ai.api.md

@@ -220,6 +220,17 @@ export interface EnhancedGenerateContentResponse extends GenerateContentResponse
     text: () => string;
 }
 
+// Warning: (ae-incompatible-release-tags) The symbol "EnumStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
+//
+// @public
+export interface EnumStringSchema extends BaseSchema {
+    enum: string[];
+    // (undocumented)
+    format: "enum";
+    // (undocumented)
+    type: typeof SchemaType.STRING;
+}
+
 // @public
 export interface ErrorDetails {
     // (undocumented)
@@ -800,6 +811,18 @@ export interface SearchEntryPoint {
     sdkBlob?: string;
 }
 
+// Warning: (ae-incompatible-release-tags) The symbol "SimpleStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
+//
+// @public
+export interface SimpleStringSchema extends BaseSchema {
+    // (undocumented)
+    enum?: never;
+    // (undocumented)
+    format?: "date-time" | undefined;
+    // (undocumented)
+    type: typeof SchemaType.STRING;
+}
+
 // @public
 export interface SingleRequestOptions extends RequestOptions {
     signal?: AbortSignal;
@@ -818,14 +841,8 @@ export interface StartChatParams extends BaseParams {
     tools?: Tool[];
 }
 
-// Warning: (ae-incompatible-release-tags) The symbol "StringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
-//
 // @public
-export interface StringSchema extends BaseSchema {
-    enum?: string[];
-    // (undocumented)
-    type: typeof SchemaType.STRING;
-}
+export type StringSchema = SimpleStringSchema | EnumStringSchema;
 
 // @public
 export enum TaskType {

docs/reference/main/generative-ai.enumstringschema.enum.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [enum](./generative-ai.enumstringschema.enum.md)
+
+## EnumStringSchema.enum property
+
+Possible values for this enum
+
+**Signature:**
+
+```typescript
+enum: string[];
+```

docs/reference/main/generative-ai.enumstringschema.format.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [format](./generative-ai.enumstringschema.format.md)
+
+## EnumStringSchema.format property
+
+**Signature:**
+
+```typescript
+format: "enum";
+```

docs/reference/main/generative-ai.enumstringschema.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md)
+
+## EnumStringSchema interface
+
+Describes a string enum
+
+**Signature:**
+
+```typescript
+export interface EnumStringSchema extends BaseSchema 
+```
+**Extends:** BaseSchema
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [enum](./generative-ai.enumstringschema.enum.md) |  | string\[\] | Possible values for this enum |
+|  [format](./generative-ai.enumstringschema.format.md) |  | "enum" |  |
+|  [type](./generative-ai.enumstringschema.type.md) |  | typeof [SchemaType.STRING](./generative-ai.schematype.md) |  |
+

docs/reference/main/generative-ai.stringschema.type.md → docs/reference/main/generative-ai.enumstringschema.type.md

@@ -1,8 +1,8 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [StringSchema](./generative-ai.stringschema.md) &gt; [type](./generative-ai.stringschema.type.md)
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [type](./generative-ai.enumstringschema.type.md)
 
-## StringSchema.type property
+## EnumStringSchema.type property
 
 **Signature:**
 

docs/reference/main/generative-ai.md

@@ -57,6 +57,7 @@
 |  [EmbedContentRequest](./generative-ai.embedcontentrequest.md) | Params for calling [GenerativeModel.embedContent()](./generative-ai.generativemodel.embedcontent.md) |
 |  [EmbedContentResponse](./generative-ai.embedcontentresponse.md) | Response from calling [GenerativeModel.embedContent()](./generative-ai.generativemodel.embedcontent.md)<!-- -->. |
 |  [EnhancedGenerateContentResponse](./generative-ai.enhancedgeneratecontentresponse.md) | Response object wrapped with helper methods. |
+|  [EnumStringSchema](./generative-ai.enumstringschema.md) | Describes a string enum |
 |  [ErrorDetails](./generative-ai.errordetails.md) | Details object that may be included in an error response. |
 |  [ExecutableCode](./generative-ai.executablecode.md) | Code generated by the model that is meant to be executed, where the result is returned to the model. Only generated when using the code execution tool, in which the code will be automatically executed, and a corresponding <code>CodeExecutionResult</code> will also be generated. |
 |  [ExecutableCodePart](./generative-ai.executablecodepart.md) | Content part containing executable code generated by the model. |
@@ -97,9 +98,9 @@
 |  [SafetyRating](./generative-ai.safetyrating.md) | A safety rating associated with a [GenerateContentCandidate](./generative-ai.generatecontentcandidate.md) |
 |  [SafetySetting](./generative-ai.safetysetting.md) | Safety setting that can be sent as part of request parameters. |
 |  [SearchEntryPoint](./generative-ai.searchentrypoint.md) | Google search entry point. |
+|  [SimpleStringSchema](./generative-ai.simplestringschema.md) | Describes a simple string schema, with or without format |
 |  [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | Params passed to atomic asynchronous operations. |
 |  [StartChatParams](./generative-ai.startchatparams.md) | Params for [GenerativeModel.startChat()](./generative-ai.generativemodel.startchat.md)<!-- -->. |
-|  [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
 |  [TextPart](./generative-ai.textpart.md) | Content part interface if the part represents a text string. |
 |  [ToolConfig](./generative-ai.toolconfig.md) | Tool config. This config is shared for all tools provided in the request. |
 |  [TopCandidates](./generative-ai.topcandidates.md) | Candidates with top log probabilities at each decoding step |
@@ -119,5 +120,6 @@
 |  [Part](./generative-ai.part.md) | Content part - includes text or image part types. |
 |  [ResponseSchema](./generative-ai.responseschema.md) | Schema passed to <code>GenerationConfig.responseSchema</code> |
 |  [Schema](./generative-ai.schema.md) | Schema is used to define the format of input/output data. Represents a select subset of an OpenAPI 3.0 schema object. More fields may be added in the future as needed. |
+|  [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
 |  [Tool](./generative-ai.tool.md) | Defines a tool that model can call to access external knowledge. |
 

docs/reference/main/generative-ai.simplestringschema.enum.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [enum](./generative-ai.simplestringschema.enum.md)
+
+## SimpleStringSchema.enum property
+
+**Signature:**
+
+```typescript
+enum?: never;
+```

docs/reference/main/generative-ai.simplestringschema.format.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [format](./generative-ai.simplestringschema.format.md)
+
+## SimpleStringSchema.format property
+
+**Signature:**
+
+```typescript
+format?: "date-time" | undefined;
+```

docs/reference/main/generative-ai.simplestringschema.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md)
+
+## SimpleStringSchema interface
+
+Describes a simple string schema, with or without format
+
+**Signature:**
+
+```typescript
+export interface SimpleStringSchema extends BaseSchema 
+```
+**Extends:** BaseSchema
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [enum?](./generative-ai.simplestringschema.enum.md) |  | never | _(Optional)_ |
+|  [format?](./generative-ai.simplestringschema.format.md) |  | "date-time" \| undefined | _(Optional)_ |
+|  [type](./generative-ai.simplestringschema.type.md) |  | typeof [SchemaType.STRING](./generative-ai.schematype.md) |  |
+

docs/reference/main/generative-ai.simplestringschema.type.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [type](./generative-ai.simplestringschema.type.md)
+
+## SimpleStringSchema.type property
+
+**Signature:**
+
+```typescript
+type: typeof SchemaType.STRING;
+```

docs/reference/main/generative-ai.stringschema.md

@@ -2,21 +2,14 @@
 
 [Home](./index.md) > [@google/generative-ai](./generative-ai.md) > [StringSchema](./generative-ai.stringschema.md)
 
-## StringSchema interface
+## StringSchema type
 
 Describes a string.
 
 **Signature:**
 
 ```typescript
-export interface StringSchema extends BaseSchema 
+export type StringSchema = SimpleStringSchema | EnumStringSchema;
 ```
-**Extends:** BaseSchema
-
-## Properties
-
-|  Property | Modifiers | Type | Description |
-|  --- | --- | --- | --- |
-|  [enum?](./generative-ai.stringschema.enum.md) |  | string\[\] | _(Optional)_ If present, limits the result to one of the given values. |
-|  [type](./generative-ai.stringschema.type.md) |  | typeof [SchemaType.STRING](./generative-ai.schematype.md) |  |
+**References:** [SimpleStringSchema](./generative-ai.simplestringschema.md)<!-- -->, [EnumStringSchema](./generative-ai.enumstringschema.md)
 

docs/reference/server/generative-ai.enumstringschema.enum.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [enum](./generative-ai.enumstringschema.enum.md)
+
+## EnumStringSchema.enum property
+
+Possible values for this enum
+
+**Signature:**
+
+```typescript
+enum: string[];
+```

docs/reference/server/generative-ai.enumstringschema.format.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [format](./generative-ai.enumstringschema.format.md)
+
+## EnumStringSchema.format property
+
+**Signature:**
+
+```typescript
+format: "enum";
+```

docs/reference/server/generative-ai.enumstringschema.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md)
+
+## EnumStringSchema interface
+
+Describes a string enum
+
+**Signature:**
+
+```typescript
+export interface EnumStringSchema extends BaseSchema 
+```
+**Extends:** BaseSchema
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [enum](./generative-ai.enumstringschema.enum.md) |  | string\[\] | Possible values for this enum |
+|  [format](./generative-ai.enumstringschema.format.md) |  | "enum" |  |
+|  [type](./generative-ai.enumstringschema.type.md) |  | typeof [SchemaType.STRING](./generative-ai.schematype.md) |  |
+

docs/reference/server/generative-ai.stringschema.type.md → docs/reference/server/generative-ai.enumstringschema.type.md

@@ -1,8 +1,8 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [StringSchema](./generative-ai.stringschema.md) &gt; [type](./generative-ai.stringschema.type.md)
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [type](./generative-ai.enumstringschema.type.md)
 
-## StringSchema.type property
+## EnumStringSchema.type property
 
 **Signature:**
 

docs/reference/server/generative-ai.md

@@ -36,6 +36,7 @@
 |  [CodeExecutionResultPart](./generative-ai.codeexecutionresultpart.md) | Content part containing the result of executed code. |
 |  [CodeExecutionTool](./generative-ai.codeexecutiontool.md) | Enables the model to execute code as part of generation. |
 |  [Content](./generative-ai.content.md) | Content type for both prompts and response candidates. |
+|  [EnumStringSchema](./generative-ai.enumstringschema.md) | Describes a string enum |
 |  [ErrorDetails](./generative-ai.errordetails.md) | Details object that may be included in an error response. |
 |  [ExecutableCode](./generative-ai.executablecode.md) | Code generated by the model that is meant to be executed, where the result is returned to the model. Only generated when using the code execution tool, in which the code will be automatically executed, and a corresponding <code>CodeExecutionResult</code> will also be generated. |
 |  [ExecutableCodePart](./generative-ai.executablecodepart.md) | Content part containing executable code generated by the model. |
@@ -61,8 +62,8 @@
 |  [ObjectSchema](./generative-ai.objectschema.md) | Describes a JSON object, a mapping of specific keys to values. |
 |  [RequestOptions](./generative-ai.requestoptions.md) | Params passed to getGenerativeModel() or GoogleAIFileManager(). |
 |  [RpcStatus](./generative-ai.rpcstatus.md) | Standard RPC error status object. |
+|  [SimpleStringSchema](./generative-ai.simplestringschema.md) | Describes a simple string schema, with or without format |
 |  [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | Params passed to atomic asynchronous operations. |
-|  [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
 |  [TextPart](./generative-ai.textpart.md) | Content part interface if the part represents a text string. |
 |  [ToolConfig](./generative-ai.toolconfig.md) | Tool config. This config is shared for all tools provided in the request. |
 |  [UploadFileResponse](./generative-ai.uploadfileresponse.md) | Response from calling [GoogleAIFileManager.uploadFile()](./generative-ai.googleaifilemanager.uploadfile.md) |
@@ -76,5 +77,6 @@
 |  [Part](./generative-ai.part.md) | Content part - includes text or image part types. |
 |  [ResponseSchema](./generative-ai.responseschema.md) | Schema passed to <code>GenerationConfig.responseSchema</code> |
 |  [Schema](./generative-ai.schema.md) | Schema is used to define the format of input/output data. Represents a select subset of an OpenAPI 3.0 schema object. More fields may be added in the future as needed. |
+|  [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
 |  [Tool](./generative-ai.tool.md) | Defines a tool that model can call to access external knowledge. |
 

docs/reference/server/generative-ai.simplestringschema.enum.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [enum](./generative-ai.simplestringschema.enum.md)
+
+## SimpleStringSchema.enum property
+
+**Signature:**
+
+```typescript
+enum?: never;
+```