Data extraction
Extract fields from unstructured text into a validated typed object.
AI Tools · Const
Structured Output
The AI SDK generates schema-conforming structured data through the output option on generateText and streamText. Choose an output specification such as Output.object() or Output.array() and supply a supported schema.
How it works
Structured output is configured through the output property of generateText or streamText. Output.object({ schema }) describes the desired object shape; the SDK uses the schema to validate the model result, providing typed structured data while retaining the normal text-generation flow.
Syntax
generateText({ model, output: Output.object({ schema }), prompt })Parameters
| Name | Type | Description |
|---|---|---|
model | LanguageModel | The language model used to generate the structured result. |
prompt | string | messages | A prompt or other text-generation input describing the requested result. |
output | Output specification | An output specification such as Output.object({ schema }) or Output.array({ element }). |
Returns
A generation result whose structured output is available as typed data and has been validated against the supplied schema.
Key points
- The API presents one structured-data interface across different model providers.
- Use
Output.object({ schema })when the desired result is one schema-defined object. - Use
Output.array()for typed lists, with optional item-count bounds.
Common mistakes
- Structured output is part of the
generateTextandstreamTextflow, so it can coexist with tool calls in one request. - A schema is not only descriptive: generated objects are checked against it before being returned.
Example: Generate a validated object
import { generateText, Output } from 'ai';
import { z } from 'zod';
const result = await generateText({
model: 'openai/gpt-4o',
output: Output.object({
schema: z.object({
title: z.string(),
summary: z.string(),
}),
}),
prompt: 'Describe the JavaScript language in two fields.',
});
console.log(result.output);This requests an object whose generated fields are validated against the supplied Zod schema.
When to use it
Typed list generation
Return a predictable list of schema-conforming records from a model request.
Tool-assisted structured responses
Combine validated final data with tool calls in one generation flow.
Interview questions
QHow do you generate structured data in the current AI SDK?
Use the output property on generateText or streamText, typically with Output.object({ schema }). The schema defines the expected shape, and the SDK validates the generated result against it.
Follow-up: How can the schema be expressed? Use a supported Zod, Valibot, or JSON Schema definition.
QHow do object and array structured outputs differ?
Output.object() describes one typed object, while Output.array() describes an array whose elements follow a supplied schema. The selected output specification is passed to the generation function through output.
Follow-up: What should be used when the response is a list? Choose Output.array() and provide the element specification.
QCan structured output and tool calling be used together?
The feature is part of the normal generateText and streamText flow rather than a separate generation pipeline. Consequently, structured generation can be combined with tool calling in the same request.
Follow-up: Why is this useful for agents? It lets a request produce validated final data while also using tools during the same flow.
Related
generateTextstreamTextOutput.objectOutput.arrayZod schemasValibot schemasJSON schemas