Skip to content

Commit 64e5af7

Browse files
IvanLHIvanLH
authored
Adds types which will enforce format rules when using String Schemas (#369)
* Revert "Changed secret to use the PAT of the bot (#359)" This reverts commit e175360. * Added new types which will help enforce format: enum when using enum field on StringSchemas * Added changeset * Fix tests * Fix docs * Removed the unnecesary date time schema interface * Fixed tests * Clarified types and rerun docs
1 parent 13466b3 commit 64e5af7

26 files changed

+308
-72
lines changed

‎.changeset/silly-coats-lie.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@google/generative-ai": minor
3+
---
4+
5+
BREAKING CHANGE: Enforce format safety when using string schemas

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

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,17 @@ export interface Content {
131131
role: string;
132132
}
133133

134+
// Warning: (ae-incompatible-release-tags) The symbol "EnumStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
135+
//
136+
// @public
137+
export interface EnumStringSchema extends BaseSchema {
138+
enum: string[];
139+
// (undocumented)
140+
format: "enum";
141+
// (undocumented)
142+
type: typeof SchemaType.STRING;
143+
}
144+
134145
// @public
135146
export interface ErrorDetails {
136147
// (undocumented)
@@ -493,19 +504,25 @@ export enum SchemaType {
493504
STRING = "string"
494505
}
495506

507+
// Warning: (ae-incompatible-release-tags) The symbol "SimpleStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
508+
//
509+
// @public
510+
export interface SimpleStringSchema extends BaseSchema {
511+
// (undocumented)
512+
enum?: never;
513+
// (undocumented)
514+
format?: "date-time" | undefined;
515+
// (undocumented)
516+
type: typeof SchemaType.STRING;
517+
}
518+
496519
// @public
497520
export interface SingleRequestOptions extends RequestOptions {
498521
signal?: AbortSignal;
499522
}
500523

501-
// Warning: (ae-incompatible-release-tags) The symbol "StringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
502-
//
503524
// @public
504-
export interface StringSchema extends BaseSchema {
505-
enum?: string[];
506-
// (undocumented)
507-
type: typeof SchemaType.STRING;
508-
}
525+
export type StringSchema = SimpleStringSchema | EnumStringSchema;
509526

510527
// @public
511528
export interface TextPart {

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

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,17 @@ export interface EnhancedGenerateContentResponse extends GenerateContentResponse
220220
text: () => string;
221221
}
222222

223+
// Warning: (ae-incompatible-release-tags) The symbol "EnumStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
224+
//
225+
// @public
226+
export interface EnumStringSchema extends BaseSchema {
227+
enum: string[];
228+
// (undocumented)
229+
format: "enum";
230+
// (undocumented)
231+
type: typeof SchemaType.STRING;
232+
}
233+
223234
// @public
224235
export interface ErrorDetails {
225236
// (undocumented)
@@ -800,6 +811,18 @@ export interface SearchEntryPoint {
800811
sdkBlob?: string;
801812
}
802813

814+
// Warning: (ae-incompatible-release-tags) The symbol "SimpleStringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
815+
//
816+
// @public
817+
export interface SimpleStringSchema extends BaseSchema {
818+
// (undocumented)
819+
enum?: never;
820+
// (undocumented)
821+
format?: "date-time" | undefined;
822+
// (undocumented)
823+
type: typeof SchemaType.STRING;
824+
}
825+
803826
// @public
804827
export interface SingleRequestOptions extends RequestOptions {
805828
signal?: AbortSignal;
@@ -818,14 +841,8 @@ export interface StartChatParams extends BaseParams {
818841
tools?: Tool[];
819842
}
820843

821-
// Warning: (ae-incompatible-release-tags) The symbol "StringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
822-
//
823844
// @public
824-
export interface StringSchema extends BaseSchema {
825-
enum?: string[];
826-
// (undocumented)
827-
type: typeof SchemaType.STRING;
828-
}
845+
export type StringSchema = SimpleStringSchema | EnumStringSchema;
829846

830847
// @public
831848
export enum TaskType {

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [enum](./generative-ai.enumstringschema.enum.md)
4+
5+
## EnumStringSchema.enum property
6+
7+
Possible values for this enum
8+
9+
**Signature:**
10+
11+
```typescript
12+
enum: string[];
13+
```

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [format](./generative-ai.enumstringschema.format.md)
4+
5+
## EnumStringSchema.format property
6+
7+
**Signature:**
8+
9+
```typescript
10+
format: "enum";
11+
```

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md)
4+
5+
## EnumStringSchema interface
6+
7+
Describes a string enum
8+
9+
**Signature:**
10+
11+
```typescript
12+
export interface EnumStringSchema extends BaseSchema
13+
```
14+
**Extends:** BaseSchema
15+
16+
## Properties
17+
18+
| Property | Modifiers | Type | Description |
19+
| --- | --- | --- | --- |
20+
| [enum](./generative-ai.enumstringschema.enum.md) | | string\[\] | Possible values for this enum |
21+
| [format](./generative-ai.enumstringschema.format.md) | | "enum" | |
22+
| [type](./generative-ai.enumstringschema.type.md) | | typeof [SchemaType.STRING](./generative-ai.schematype.md) | |
23+

‎docs/reference/main/generative-ai.stringschema.type.md renamed to ‎docs/reference/main/generative-ai.enumstringschema.type.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
22

3-
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [StringSchema](./generative-ai.stringschema.md) &gt; [type](./generative-ai.stringschema.type.md)
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [type](./generative-ai.enumstringschema.type.md)
44

5-
## StringSchema.type property
5+
## EnumStringSchema.type property
66

77
**Signature:**
88

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
| [EmbedContentRequest](./generative-ai.embedcontentrequest.md) | Params for calling [GenerativeModel.embedContent()](./generative-ai.generativemodel.embedcontent.md) |
5858
| [EmbedContentResponse](./generative-ai.embedcontentresponse.md) | Response from calling [GenerativeModel.embedContent()](./generative-ai.generativemodel.embedcontent.md)<!-- -->. |
5959
| [EnhancedGenerateContentResponse](./generative-ai.enhancedgeneratecontentresponse.md) | Response object wrapped with helper methods. |
60+
| [EnumStringSchema](./generative-ai.enumstringschema.md) | Describes a string enum |
6061
| [ErrorDetails](./generative-ai.errordetails.md) | Details object that may be included in an error response. |
6162
| [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. |
6263
| [ExecutableCodePart](./generative-ai.executablecodepart.md) | Content part containing executable code generated by the model. |
@@ -97,9 +98,9 @@
9798
| [SafetyRating](./generative-ai.safetyrating.md) | A safety rating associated with a [GenerateContentCandidate](./generative-ai.generatecontentcandidate.md) |
9899
| [SafetySetting](./generative-ai.safetysetting.md) | Safety setting that can be sent as part of request parameters. |
99100
| [SearchEntryPoint](./generative-ai.searchentrypoint.md) | Google search entry point. |
101+
| [SimpleStringSchema](./generative-ai.simplestringschema.md) | Describes a simple string schema, with or without format |
100102
| [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | Params passed to atomic asynchronous operations. |
101103
| [StartChatParams](./generative-ai.startchatparams.md) | Params for [GenerativeModel.startChat()](./generative-ai.generativemodel.startchat.md)<!-- -->. |
102-
| [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
103104
| [TextPart](./generative-ai.textpart.md) | Content part interface if the part represents a text string. |
104105
| [ToolConfig](./generative-ai.toolconfig.md) | Tool config. This config is shared for all tools provided in the request. |
105106
| [TopCandidates](./generative-ai.topcandidates.md) | Candidates with top log probabilities at each decoding step |
@@ -119,5 +120,6 @@
119120
| [Part](./generative-ai.part.md) | Content part - includes text or image part types. |
120121
| [ResponseSchema](./generative-ai.responseschema.md) | Schema passed to <code>GenerationConfig.responseSchema</code> |
121122
| [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. |
123+
| [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
122124
| [Tool](./generative-ai.tool.md) | Defines a tool that model can call to access external knowledge. |
123125

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [enum](./generative-ai.simplestringschema.enum.md)
4+
5+
## SimpleStringSchema.enum property
6+
7+
**Signature:**
8+
9+
```typescript
10+
enum?: never;
11+
```

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [format](./generative-ai.simplestringschema.format.md)
4+
5+
## SimpleStringSchema.format property
6+
7+
**Signature:**
8+
9+
```typescript
10+
format?: "date-time" | undefined;
11+
```

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md)
4+
5+
## SimpleStringSchema interface
6+
7+
Describes a simple string schema, with or without format
8+
9+
**Signature:**
10+
11+
```typescript
12+
export interface SimpleStringSchema extends BaseSchema
13+
```
14+
**Extends:** BaseSchema
15+
16+
## Properties
17+
18+
| Property | Modifiers | Type | Description |
19+
| --- | --- | --- | --- |
20+
| [enum?](./generative-ai.simplestringschema.enum.md) | | never | _(Optional)_ |
21+
| [format?](./generative-ai.simplestringschema.format.md) | | "date-time" \| undefined | _(Optional)_ |
22+
| [type](./generative-ai.simplestringschema.type.md) | | typeof [SchemaType.STRING](./generative-ai.schematype.md) | |
23+

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [type](./generative-ai.simplestringschema.type.md)
4+
5+
## SimpleStringSchema.type property
6+
7+
**Signature:**
8+
9+
```typescript
10+
type: typeof SchemaType.STRING;
11+
```

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

Lines changed: 0 additions & 13 deletions
This file was deleted.

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

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,14 @@
22

33
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [StringSchema](./generative-ai.stringschema.md)
44

5-
## StringSchema interface
5+
## StringSchema type
66

77
Describes a string.
88

99
**Signature:**
1010

1111
```typescript
12-
export interface StringSchema extends BaseSchema
12+
export type StringSchema = SimpleStringSchema | EnumStringSchema;
1313
```
14-
**Extends:** BaseSchema
15-
16-
## Properties
17-
18-
| Property | Modifiers | Type | Description |
19-
| --- | --- | --- | --- |
20-
| [enum?](./generative-ai.stringschema.enum.md) | | string\[\] | _(Optional)_ If present, limits the result to one of the given values. |
21-
| [type](./generative-ai.stringschema.type.md) | | typeof [SchemaType.STRING](./generative-ai.schematype.md) | |
14+
**References:** [SimpleStringSchema](./generative-ai.simplestringschema.md)<!-- -->, [EnumStringSchema](./generative-ai.enumstringschema.md)
2215

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [enum](./generative-ai.enumstringschema.enum.md)
4+
5+
## EnumStringSchema.enum property
6+
7+
Possible values for this enum
8+
9+
**Signature:**
10+
11+
```typescript
12+
enum: string[];
13+
```

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [format](./generative-ai.enumstringschema.format.md)
4+
5+
## EnumStringSchema.format property
6+
7+
**Signature:**
8+
9+
```typescript
10+
format: "enum";
11+
```

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md)
4+
5+
## EnumStringSchema interface
6+
7+
Describes a string enum
8+
9+
**Signature:**
10+
11+
```typescript
12+
export interface EnumStringSchema extends BaseSchema
13+
```
14+
**Extends:** BaseSchema
15+
16+
## Properties
17+
18+
| Property | Modifiers | Type | Description |
19+
| --- | --- | --- | --- |
20+
| [enum](./generative-ai.enumstringschema.enum.md) | | string\[\] | Possible values for this enum |
21+
| [format](./generative-ai.enumstringschema.format.md) | | "enum" | |
22+
| [type](./generative-ai.enumstringschema.type.md) | | typeof [SchemaType.STRING](./generative-ai.schematype.md) | |
23+

‎docs/reference/server/generative-ai.stringschema.type.md renamed to ‎docs/reference/server/generative-ai.enumstringschema.type.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
22

3-
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [StringSchema](./generative-ai.stringschema.md) &gt; [type](./generative-ai.stringschema.type.md)
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [EnumStringSchema](./generative-ai.enumstringschema.md) &gt; [type](./generative-ai.enumstringschema.type.md)
44

5-
## StringSchema.type property
5+
## EnumStringSchema.type property
66

77
**Signature:**
88

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
| [CodeExecutionResultPart](./generative-ai.codeexecutionresultpart.md) | Content part containing the result of executed code. |
3737
| [CodeExecutionTool](./generative-ai.codeexecutiontool.md) | Enables the model to execute code as part of generation. |
3838
| [Content](./generative-ai.content.md) | Content type for both prompts and response candidates. |
39+
| [EnumStringSchema](./generative-ai.enumstringschema.md) | Describes a string enum |
3940
| [ErrorDetails](./generative-ai.errordetails.md) | Details object that may be included in an error response. |
4041
| [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. |
4142
| [ExecutableCodePart](./generative-ai.executablecodepart.md) | Content part containing executable code generated by the model. |
@@ -61,8 +62,8 @@
6162
| [ObjectSchema](./generative-ai.objectschema.md) | Describes a JSON object, a mapping of specific keys to values. |
6263
| [RequestOptions](./generative-ai.requestoptions.md) | Params passed to getGenerativeModel() or GoogleAIFileManager(). |
6364
| [RpcStatus](./generative-ai.rpcstatus.md) | Standard RPC error status object. |
65+
| [SimpleStringSchema](./generative-ai.simplestringschema.md) | Describes a simple string schema, with or without format |
6466
| [SingleRequestOptions](./generative-ai.singlerequestoptions.md) | Params passed to atomic asynchronous operations. |
65-
| [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
6667
| [TextPart](./generative-ai.textpart.md) | Content part interface if the part represents a text string. |
6768
| [ToolConfig](./generative-ai.toolconfig.md) | Tool config. This config is shared for all tools provided in the request. |
6869
| [UploadFileResponse](./generative-ai.uploadfileresponse.md) | Response from calling [GoogleAIFileManager.uploadFile()](./generative-ai.googleaifilemanager.uploadfile.md) |
@@ -76,5 +77,6 @@
7677
| [Part](./generative-ai.part.md) | Content part - includes text or image part types. |
7778
| [ResponseSchema](./generative-ai.responseschema.md) | Schema passed to <code>GenerationConfig.responseSchema</code> |
7879
| [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. |
80+
| [StringSchema](./generative-ai.stringschema.md) | Describes a string. |
7981
| [Tool](./generative-ai.tool.md) | Defines a tool that model can call to access external knowledge. |
8082

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [SimpleStringSchema](./generative-ai.simplestringschema.md) &gt; [enum](./generative-ai.simplestringschema.enum.md)
4+
5+
## SimpleStringSchema.enum property
6+
7+
**Signature:**
8+
9+
```typescript
10+
enum?: never;
11+
```

0 commit comments

Comments
 (0)