Skip to content

Commit 3004d3b

Browse files
ricticrictic
authored
Make Schema a discriminated union (#296)
* Make Schema a discriminated union This leverages the type system to better describe the API's requirements for schemas. For example, rather than saying that any schema might have an optional `items` property, we're able to express that `items` is required on array schemas and forbidden on all others. More info on discriminated unions: https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions * Update docs.
1 parent 6a99ed8 commit 3004d3b

File tree

69 files changed

+892
-337
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

69 files changed

+892
-337
lines changed

‎.changeset/young-rivers-shout.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+
The schema types are now more specific, using a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions) based on the 'type' field to more accurately define which fields are allowed.

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

Lines changed: 69 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,33 @@
44
55
```ts
66

7+
// Warning: (ae-incompatible-release-tags) The symbol "ArraySchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
8+
//
9+
// @public
10+
export interface ArraySchema extends BaseSchema {
11+
items: Schema;
12+
maxItems?: number;
13+
minItems?: number;
14+
// (undocumented)
15+
type: typeof SchemaType.ARRAY;
16+
}
17+
18+
// Warning: (ae-internal-missing-underscore) The name "BaseSchema" should be prefixed with an underscore because the declaration is marked as @internal
19+
//
20+
// @internal
21+
export interface BaseSchema {
22+
description?: string;
23+
nullable?: boolean;
24+
}
25+
26+
// Warning: (ae-incompatible-release-tags) The symbol "BooleanSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
27+
//
28+
// @public
29+
export interface BooleanSchema extends BaseSchema {
30+
// (undocumented)
31+
type: typeof SchemaType.BOOLEAN;
32+
}
33+
734
// @public
835
export interface CachedContent extends CachedContentBase {
936
createTime?: string;
@@ -286,8 +313,7 @@ export interface FunctionDeclarationSchema {
286313
}
287314

288315
// @public
289-
export interface FunctionDeclarationSchemaProperty extends Schema {
290-
}
316+
export type FunctionDeclarationSchemaProperty = Schema;
291317

292318
// @public
293319
export interface FunctionDeclarationsTool {
@@ -368,6 +394,15 @@ export interface InlineDataPart {
368394
text?: never;
369395
}
370396

397+
// Warning: (ae-incompatible-release-tags) The symbol "IntegerSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
398+
//
399+
// @public
400+
export interface IntegerSchema extends BaseSchema {
401+
format?: "int32" | "int64";
402+
// (undocumented)
403+
type: typeof SchemaType.INTEGER;
404+
}
405+
371406
// @public (undocumented)
372407
export interface ListCacheResponse {
373408
// (undocumented)
@@ -392,6 +427,27 @@ export interface ListParams {
392427
pageToken?: string;
393428
}
394429

430+
// Warning: (ae-incompatible-release-tags) The symbol "NumberSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
431+
//
432+
// @public
433+
export interface NumberSchema extends BaseSchema {
434+
format?: "float" | "double";
435+
// (undocumented)
436+
type: typeof SchemaType.NUMBER;
437+
}
438+
439+
// Warning: (ae-incompatible-release-tags) The symbol "ObjectSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
440+
//
441+
// @public
442+
export interface ObjectSchema extends BaseSchema {
443+
properties: {
444+
[k: string]: Schema;
445+
};
446+
required?: string[];
447+
// (undocumented)
448+
type: typeof SchemaType.OBJECT;
449+
}
450+
395451
// @public
396452
export enum Outcome {
397453
OUTCOME_DEADLINE_EXCEEDED = "outcome_deadline_exceeded",
@@ -413,8 +469,7 @@ export interface RequestOptions {
413469
}
414470

415471
// @public
416-
export interface ResponseSchema extends Schema {
417-
}
472+
export type ResponseSchema = Schema;
418473

419474
// @public
420475
export interface RpcStatus {
@@ -424,19 +479,7 @@ export interface RpcStatus {
424479
}
425480

426481
// @public
427-
export interface Schema {
428-
description?: string;
429-
enum?: string[];
430-
example?: unknown;
431-
format?: string;
432-
items?: Schema;
433-
nullable?: boolean;
434-
properties?: {
435-
[k: string]: Schema;
436-
};
437-
required?: string[];
438-
type?: SchemaType;
439-
}
482+
export type Schema = StringSchema | NumberSchema | IntegerSchema | BooleanSchema | ArraySchema | ObjectSchema;
440483

441484
// @public
442485
export enum SchemaType {
@@ -453,6 +496,15 @@ export interface SingleRequestOptions extends RequestOptions {
453496
signal?: AbortSignal;
454497
}
455498

499+
// Warning: (ae-incompatible-release-tags) The symbol "StringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
500+
//
501+
// @public
502+
export interface StringSchema extends BaseSchema {
503+
enum?: string[];
504+
// (undocumented)
505+
type: typeof SchemaType.STRING;
506+
}
507+
456508
// @public
457509
export interface TextPart {
458510
// (undocumented)

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

Lines changed: 69 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,17 @@
44
55
```ts
66

7+
// Warning: (ae-incompatible-release-tags) The symbol "ArraySchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
8+
//
9+
// @public
10+
export interface ArraySchema extends BaseSchema {
11+
items: Schema;
12+
maxItems?: number;
13+
minItems?: number;
14+
// (undocumented)
15+
type: typeof SchemaType.ARRAY;
16+
}
17+
718
// @public
819
export interface BaseParams {
920
// (undocumented)
@@ -12,6 +23,14 @@ export interface BaseParams {
1223
safetySettings?: SafetySetting[];
1324
}
1425

26+
// Warning: (ae-internal-missing-underscore) The name "BaseSchema" should be prefixed with an underscore because the declaration is marked as @internal
27+
//
28+
// @internal
29+
export interface BaseSchema {
30+
description?: string;
31+
nullable?: boolean;
32+
}
33+
1534
// @public
1635
export interface BatchEmbedContentsRequest {
1736
// (undocumented)
@@ -34,6 +53,14 @@ export enum BlockReason {
3453
SAFETY = "SAFETY"
3554
}
3655

56+
// Warning: (ae-incompatible-release-tags) The symbol "BooleanSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
57+
//
58+
// @public
59+
export interface BooleanSchema extends BaseSchema {
60+
// (undocumented)
61+
type: typeof SchemaType.BOOLEAN;
62+
}
63+
3764
// @public
3865
export interface CachedContent extends CachedContentBase {
3966
createTime?: string;
@@ -355,8 +382,7 @@ export interface FunctionDeclarationSchema {
355382
}
356383

357384
// @public
358-
export interface FunctionDeclarationSchemaProperty extends Schema {
359-
}
385+
export type FunctionDeclarationSchemaProperty = Schema;
360386

361387
// @public
362388
export interface FunctionDeclarationsTool {
@@ -645,6 +671,15 @@ export interface InlineDataPart {
645671
text?: never;
646672
}
647673

674+
// Warning: (ae-incompatible-release-tags) The symbol "IntegerSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
675+
//
676+
// @public
677+
export interface IntegerSchema extends BaseSchema {
678+
format?: "int32" | "int64";
679+
// (undocumented)
680+
type: typeof SchemaType.INTEGER;
681+
}
682+
648683
// @public
649684
export interface LogprobsCandidate {
650685
logProbability: number;
@@ -672,6 +707,27 @@ export interface ModelParams extends BaseParams {
672707
tools?: Tool[];
673708
}
674709

710+
// Warning: (ae-incompatible-release-tags) The symbol "NumberSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
711+
//
712+
// @public
713+
export interface NumberSchema extends BaseSchema {
714+
format?: "float" | "double";
715+
// (undocumented)
716+
type: typeof SchemaType.NUMBER;
717+
}
718+
719+
// Warning: (ae-incompatible-release-tags) The symbol "ObjectSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
720+
//
721+
// @public
722+
export interface ObjectSchema extends BaseSchema {
723+
properties: {
724+
[k: string]: Schema;
725+
};
726+
required?: string[];
727+
// (undocumented)
728+
type: typeof SchemaType.OBJECT;
729+
}
730+
675731
// @public
676732
export enum Outcome {
677733
OUTCOME_DEADLINE_EXCEEDED = "outcome_deadline_exceeded",
@@ -706,8 +762,7 @@ export interface RequestOptions {
706762
}
707763

708764
// @public
709-
export interface ResponseSchema extends Schema {
710-
}
765+
export type ResponseSchema = Schema;
711766

712767
// @public
713768
export interface RetrievalMetadata {
@@ -731,19 +786,7 @@ export interface SafetySetting {
731786
}
732787

733788
// @public
734-
export interface Schema {
735-
description?: string;
736-
enum?: string[];
737-
example?: unknown;
738-
format?: string;
739-
items?: Schema;
740-
nullable?: boolean;
741-
properties?: {
742-
[k: string]: Schema;
743-
};
744-
required?: string[];
745-
type?: SchemaType;
746-
}
789+
export type Schema = StringSchema | NumberSchema | IntegerSchema | BooleanSchema | ArraySchema | ObjectSchema;
747790

748791
// @public
749792
export enum SchemaType {
@@ -779,6 +822,15 @@ export interface StartChatParams extends BaseParams {
779822
tools?: Tool[];
780823
}
781824

825+
// Warning: (ae-incompatible-release-tags) The symbol "StringSchema" is marked as @public, but its signature references "BaseSchema" which is marked as @internal
826+
//
827+
// @public
828+
export interface StringSchema extends BaseSchema {
829+
enum?: string[];
830+
// (undocumented)
831+
type: typeof SchemaType.STRING;
832+
}
833+
782834
// @public
783835
export enum TaskType {
784836
// (undocumented)

‎docs/reference/main/generative-ai.arrayschema.items.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; [ArraySchema](./generative-ai.arrayschema.md) &gt; [items](./generative-ai.arrayschema.items.md)
4+
5+
## ArraySchema.items property
6+
7+
A schema describing the entries in the array.
8+
9+
**Signature:**
10+
11+
```typescript
12+
items: Schema;
13+
```

‎docs/reference/main/generative-ai.arrayschema.maxitems.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; [ArraySchema](./generative-ai.arrayschema.md) &gt; [maxItems](./generative-ai.arrayschema.maxitems.md)
4+
5+
## ArraySchema.maxItems property
6+
7+
The maximum number of items in the array.
8+
9+
**Signature:**
10+
11+
```typescript
12+
maxItems?: number;
13+
```

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
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; [ArraySchema](./generative-ai.arrayschema.md)
4+
5+
## ArraySchema interface
6+
7+
Describes an array, an ordered list of values.
8+
9+
**Signature:**
10+
11+
```typescript
12+
export interface ArraySchema extends BaseSchema
13+
```
14+
**Extends:** BaseSchema
15+
16+
## Properties
17+
18+
| Property | Modifiers | Type | Description |
19+
| --- | --- | --- | --- |
20+
| [items](./generative-ai.arrayschema.items.md) | | [Schema](./generative-ai.schema.md) | A schema describing the entries in the array. |
21+
| [maxItems?](./generative-ai.arrayschema.maxitems.md) | | number | _(Optional)_ The maximum number of items in the array. |
22+
| [minItems?](./generative-ai.arrayschema.minitems.md) | | number | _(Optional)_ The minimum number of items in the array. |
23+
| [type](./generative-ai.arrayschema.type.md) | | typeof [SchemaType.ARRAY](./generative-ai.schematype.md) | |
24+

‎docs/reference/main/generative-ai.arrayschema.minitems.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; [ArraySchema](./generative-ai.arrayschema.md) &gt; [minItems](./generative-ai.arrayschema.minitems.md)
4+
5+
## ArraySchema.minItems property
6+
7+
The minimum number of items in the array.
8+
9+
**Signature:**
10+
11+
```typescript
12+
minItems?: number;
13+
```

‎docs/reference/main/generative-ai.schema.enum.md renamed to ‎docs/reference/main/generative-ai.arrayschema.type.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
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; [Schema](./generative-ai.schema.md) &gt; [enum](./generative-ai.schema.enum.md)
3+
[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [ArraySchema](./generative-ai.arrayschema.md) &gt; [type](./generative-ai.arrayschema.type.md)
44

5-
## Schema.enum property
6-
7-
Optional. The enum of the property.
5+
## ArraySchema.type property
86

97
**Signature:**
108

119
```typescript
12-
enum?: string[];
10+
type: typeof SchemaType.ARRAY;
1311
```

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
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; [BooleanSchema](./generative-ai.booleanschema.md)
4+
5+
## BooleanSchema interface
6+
7+
Describes a boolean, either 'true' or 'false'.
8+
9+
**Signature:**
10+
11+
```typescript
12+
export interface BooleanSchema extends BaseSchema
13+
```
14+
**Extends:** BaseSchema
15+
16+
## Properties
17+
18+
| Property | Modifiers | Type | Description |
19+
| --- | --- | --- | --- |
20+
| [type](./generative-ai.booleanschema.type.md) | | typeof [SchemaType.BOOLEAN](./generative-ai.schematype.md) | |
21+

0 commit comments

Comments
 (0)