Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

ResponseFormat.md

151 lines3.2 KB

1---
2id: ResponseFormat
3title: ResponseFormat
4---
5​
6# Interface: ResponseFormat\<TData\>
7​
8Defined in: [types.ts:435](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L435)
9​
10Structured output format specification.
11​
12Constrains the model's output to match a specific JSON structure.
13Useful for extracting structured data, form filling, or ensuring consistent response formats.
14​
15## See
16​
17 - https://platform.openai.com/docs/guides/structured-outputs
18 - https://sdk.vercel.ai/docs/ai-sdk-core/structured-outputs
19​
20## Type Parameters
21​
22### TData
23​
24`TData` = `any`
25​
26TypeScript type of the expected data structure (for type safety)
27​
28## Properties
29​
30### \_\_data?
31​
32```ts
33optional __data: TData;
34```
35​
36Defined in: [types.ts:513](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L513)
37​
38**`Internal`**
39​
40Type-only property to carry the inferred data type.
41​
42This is never set at runtime - it only exists for TypeScript type inference.
43Allows the SDK to know what type to expect when parsing the response.
44​
45***
46​
47### json\_schema?
48​
49```ts
50optional json_schema: object;
51```
52​
53Defined in: [types.ts:452](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L452)
54​
55JSON schema specification (required when type is "json_schema").
56​
57Defines the exact structure the model's output must conform to.
58OpenAI's structured outputs will guarantee the output matches this schema.
59​
60#### description?
61​
62```ts
63optional description: string;
64```
65​
66Optional description of what the schema represents.
67​
68Helps document the purpose of this structured output.
69​
70##### Example
71​
72```ts
73"User profile information including name, email, and preferences"
74```
75​
76#### name
77​
78```ts
79name: string;
80```
81​
82Unique name for the schema.
83​
84Used to identify the schema in logs and debugging.
85Should be descriptive (e.g., "user_profile", "search_results").
86​
87#### schema
88​
89```ts
90schema: Record<string, any>;
91```
92​
93JSON Schema definition for the expected output structure.
94​
95Must be a valid JSON Schema (draft 2020-12 or compatible).
96The model's output will be validated against this schema.
97​
98##### See
99​
100https://json-schema.org/
101​
102##### Example
103​
104```ts
106 * type: "object",
107 * properties: {
108 * name: { type: "string" },
109 * age: { type: "number" },
110 * email: { type: "string", format: "email" }
111 * },
112 * required: ["name", "email"],
113 * additionalProperties: false
114 * }
115```
116​
117#### strict?
118​
119```ts
120optional strict: boolean;
121```
122​
123Whether to enforce strict schema validation.
124​
125When true (recommended), the model guarantees output will match the schema exactly.
126When false, the model will "best effort" match the schema.
127​
128Default: true (for providers that support it)
129​
130##### See
131​
132https://platform.openai.com/docs/guides/structured-outputs#strict-mode
133​
134***
135​
136### type
137​
138```ts
139type: "json_object" | "json_schema";
140```
141​
142Defined in: [types.ts:444](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L444)
143​
144Type of structured output.
145​
146- "json_object": Forces the model to output valid JSON (any structure)
147- "json_schema": Validates output against a provided JSON Schema (strict structure)
148​
149#### See
150​
151https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format