Structured Output That Remembers Across Turns

TanStack's AI SDK now preserves structured output across chat turns by attaching typed data to each message, eliminating the need for manual state management. The update adds a `structured-output` part type to every `UIMessage`, allowing developers to access validated objects from previous turns without custom history plumbing. This change simplifies multi-turn workflows like recipe refinement and form filling, reducing boilerplate code in applications using the `useChat` hook with `outputSchema`.

by Alem Tuzlak on May 19, 2026. You ask the LLM for a recipe. It plates up Spaghetti Pomodoro — title, cuisine, servings, ingredients, steps, all typed against your schema. Beautiful. You ask it to make the recipe vegan. A new recipe streams in. Then the first one vanishes. That used to be the deal with useChat { outputSchema } : one hook-level partial / final slot. The instant a new turn started streaming, the previous turn's recipe was clobbered. Multi-turn anything recipe refinement, ticket triage, iterative form filling needed manual history plumbing — you'd intercept every chunk, snapshot final into your own state, juggle a recipes array yourself, and keep it in sync with messages to avoid drift. The schema's type safety also stopped at partial / final; once a structured payload landed in your local array, it was unknown again unless you cast. We just shipped a different shape. Every assistant turn now carries its own typed structured-output part on its UIMessage. History is preserved by default. The schema generic threads all the way down to messages i .parts.find p = p.type === 'structured-output' .data — no casts, no manual tracking. Same useChat hook, same outputSchema option, less code in your component. If you missed the prior post on streaming a single typed object end-to-end, start here https://tanstack.com/blog/streaming-structured-output — that piece is the antecedent to this one. This post walks through what changed, why it matters for any multi-turn UI, and how to build the recipe-builder pattern end-to-end in roughly 80 lines split across a server route and a client component . The previous useChat { outputSchema } exposed two values that tracked the current run: On a single-turn extractor paste a paragraph → get a typed Person , this was perfect. Field-by-field reveal as the JSON streamed, validated payload on terminal event, one render to consume both. On a multi-turn chat it fell apart. partial and final were a single slot , scoped to whichever run was most recent. As soon as you called sendMessage again, the previous turn's final was gone. The runtime had no place to keep it — the typed structured payload didn't live on the message itself, only in this transient hook state. The workaround we'd see in user code: const recipes, setRecipes = useState<Array<Recipe const { sendMessage, final } = useChat { outputSchema: RecipeSchema, connection: fetchServerSentEvents '/api/recipes' , onFinish: = { if final setRecipes prev = ...prev, final }, } const recipes, setRecipes = useState<Array<Recipe const { sendMessage, final } = useChat { outputSchema: RecipeSchema, connection: fetchServerSentEvents '/api/recipes' , onFinish: = { if final setRecipes prev = ...prev, final }, } Three problems with that: The right place for this state is on the message it came from . That's what we shipped. Every UIMessage has a parts: MessagePart array. Before, the variants were text, image, audio, video, document, tool-call, tool-result, thinking. We added one: type StructuredOutputPart<TData = unknown = { type: 'structured-output' status: 'streaming' | 'complete' | 'error' / Progressive parse — populated while streaming and after complete. / partial?: DeepPartial<TData / Validated final object — set when status === 'complete'. / data?: TData / Accumulating JSON buffer — source of truth for the wire round-trip. / raw: string reasoning?: string errorMessage?: string } type StructuredOutputPart<TData = unknown = { type: 'structured-output' status: 'streaming' | 'complete' | 'error' / Progressive parse — populated while streaming and after complete. / partial?: DeepPartial<TData / Validated final object — set when status === 'complete'. / data?: TData / Accumulating JSON buffer — source of truth for the wire round-trip. / raw: string reasoning?: string errorMessage?: string } The runtime routes TEXT MESSAGE CONTENT deltas the streaming JSON bytes into this part instead of building a TextPart. On the terminal structured-output.complete event, status flips to 'complete' and data is populated with the validated object. Every assistant turn produces a new assistant message, which carries its own structured-output part. The previous turn's part is untouched. The hook-level partial and final still exist, they're derived from the latest assistant message's part now, instead of being a sticky slot. That means they read {} and null between sendMessage and the first chunk because no new assistant message exists yet , and they snap to the freshest turn's payload as it streams. The migration is zero, the same code that read partial / final for a single-turn extractor reads identical values in the new shape. What changed is everything else . Walking messages now exposes the full history of typed objects: js type RecipePart = StructuredOutputPart<Recipe messages.map m = { if m.role === 'assistant' { const part = m.parts.find p : p is RecipePart = p.type === 'structured-output', // part.data is Recipe the schema-inferred type — no cast. // part.partial is DeepPartial<Recipe . if part return <RecipeCard part={part} / } return null } js type RecipePart = StructuredOutputPart<Recipe messages.map m = { if m.role === 'assistant' { const part = m.parts.find p : p is RecipePart = p.type === 'structured-output', // part.data is Recipe the schema-inferred type — no cast. // part.partial is DeepPartial<Recipe . if part return <RecipeCard part={part} / } return null } The schema generic flows through useChat<TTools, TSchema → UIMessage<TTools, TData → MessagePart<TTools, TData → StructuredOutputPart<TData , so part.data resolves to Recipe with no cast. The RecipePart alias is for readability; you can inline Extract<typeof p, { type: 'structured-output' } instead if you'd rather not name it. The same flow runs in Vue computed , Solid createMemo , and Svelte $derived.by — the parity work shipped in the same release. Here's the full recipe-builder pattern. Server endpoint first: js // app/api/recipes/route.ts import { chat, toServerSentEventsResponse } from '@tanstack/ai' import { openaiText } from '@tanstack/ai-openai' import { z } from 'zod' export const RecipeSchema = z.object { title: z.string , cuisine: z.string , servings: z.number , estimatedCostUsd: z.number , ingredients: z.array z.object { item: z.string , amount: z.string } , steps: z.array z.string , tips: z.array z.string , } export type Recipe = z.infer<typeof RecipeSchema const SYSTEM = You are a chef. Reply with a single recipe matching the JSON schema. When the user asks for modifications, produce a new recipe in the same shape that reflects the change. export async function POST request: Request { const { messages } = await request.json const stream = chat { adapter: openaiText 'gpt-5.2' , messages, systemPrompts: SYSTEM , outputSchema: RecipeSchema, stream: true, } return toServerSentEventsResponse stream } js // app/api/recipes/route.ts import { chat, toServerSentEventsResponse } from '@tanstack/ai' import { openaiText } from '@tanstack/ai-openai' import { z } from 'zod' export const RecipeSchema = z.object { title: z.string , cuisine: z.string , servings: z.number , estimatedCostUsd: z.number , ingredients: z.array z.object { item: z.string , amount: z.string } , steps: z.array z.string , tips: z.array z.string , } export type Recipe = z.infer<typeof RecipeSchema const SYSTEM = You are a chef. Reply with a single recipe matching the JSON schema. When the user asks for modifications, produce a new recipe in the same shape that reflects the change. export async function POST request: Request { const { messages } = await request.json const stream = chat { adapter: openaiText 'gpt-5.2' , messages, systemPrompts: SYSTEM , outputSchema: RecipeSchema, stream: true, } return toServerSentEventsResponse stream } That's the whole server side. The only structured-output-specific lines are outputSchema: RecipeSchema and stream: true. The runtime takes care of converting the schema to JSON Schema, hitting the provider's native structured-output API, validating the response, and emitting structured-output.start + structured-output.complete events to the client. Client: js import { useState } from 'react' import { useChat, fetchServerSentEvents } from '@tanstack/ai-react' import type { StructuredOutputPart } from '@tanstack/ai-client' import { RecipeSchema, type Recipe } from './api/recipes' type RecipePart = StructuredOutputPart<Recipe export function RecipeBuilder { const input, setInput = useState '' const { messages, sendMessage, isLoading } = useChat { outputSchema: RecipeSchema, connection: fetchServerSentEvents '/api/recipes' , } return <div {messages.map m = { if m.role === 'user' { const text = m.parts .filter p = p.type === 'text' .map p = p.content .join '' return <UserPrompt key={m.id} text={text} / } if m.role === 'assistant' { const part = m.parts.find p : p is RecipePart = p.type === 'structured-output', if part return null return <RecipeCard key={m.id} part={part} / } return null } } <input value={input} onChange={ e = setInput e.target.value } / <button onClick={ = { sendMessage input setInput '' }} disabled={isLoading || input.trim } {isLoading ? 'Cooking…' : 'Cook'} </button </div } function RecipeCard { part }: { part: RecipePart } { // data is Recipe typed by the schema . partial is DeepPartial<Recipe . // Both are typed — no cast, no unknown . const recipe = part.data ?? part.partial ?? {} return <article <h3 {recipe.title ?? 'Plating up…'}</h3 {recipe.cuisine && <p {recipe.cuisine}</p } {recipe.ingredients?.map ing, i = <li key={i} {ing?.amount} {ing?.item} </li } </article } js import { useState } from 'react' import { useChat, fetchServerSentEvents } from '@tanstack/ai-react' import type { StructuredOutputPart } from '@tanstack/ai-client' import { RecipeSchema, type Recipe } from './api/recipes' type RecipePart = StructuredOutputPart<Recipe export function RecipeBuilder { const input, setInput = useState '' const { messages, sendMessage, isLoading } = useChat { outputSchema: RecipeSchema, connection: fetchServerSentEvents '/api/recipes' , } return <div {messages.map m = { if m.role === 'user' { const text = m.parts .filter p = p.type === 'text' .map p = p.content .join '' return <UserPrompt key={m.id} text={text} / } if m.role === 'assistant' { const part = m.parts.find p : p is RecipePart = p.type === 'structured-output', if part return null return <RecipeCard key={m.id} part={part} / } return null } } <input value={input} onChange={ e = setInput e.target.value } / <button onClick={ = { sendMessage input setInput '' }} disabled={isLoading || input.trim } {isLoading ? 'Cooking…' : 'Cook'} </button </div } function RecipeCard { part }: { part: RecipePart } { // data is Recipe typed by the schema . partial is DeepPartial<Recipe . // Both are typed — no cast, no unknown . const recipe = part.data ?? part.partial ?? {} return <article <h3 {recipe.title ?? 'Plating up…'}</h3 {recipe.cuisine && <p {recipe.cuisine}</p } {recipe.ingredients?.map ing, i = <li key={i} {ing?.amount} {ing?.item} </li } </article } That's the entire client side. There's no separate recipes state, no onFinish callback, no manual history sync. Each sendMessage triggers a new run, which produces a new assistant message, which carries its own typed structured-output part. The render loop walks messages and the new card just lands. Try it: "Pasta dinner for two, under $15." → recipe lands. "Now make it vegan." → second recipe lands. The first is still on screen. "Add a salad and make it gluten-free." → third recipe lands. Both previous turns are still there. Multi-turn structured chats only work if the model sees its own prior responses on each follow-up turn. Otherwise turn N+1 has no idea what "make it vegan" refers to. The wire layer handles this. When useChat sends turn N+1, it serializes the conversation back through uiMessageToModelMessages. For each assistant message with a completed structured-output part, the converter emits: { role: 'assistant', content: part.raw } { role: 'assistant', content: part.raw } part.raw is the original JSON the model produced, preserved byte-for-byte from the streaming bytes that built the part in the first place. The model sees its own prior recipe verbatim and can reason about modifications. There's a defensive fallback JSON.stringify part.data for terminal-only completes that arrived without streamed bytes, plus a "drop the turn if we can't serialize it" guard for unserializable data like BigInts or circular refs. Streaming and errored parts are dropped from the round-trip; you don't want to feed an incomplete JSON fragment back to the LLM. You don't see any of this. You called sendMessage 'now make it vegan' and the model knew what it was modifying. The same release shipped parity across the framework hook packages: @tanstack/ai-react, @tanstack/ai-vue, @tanstack/ai-solid, and @tanstack/ai-svelte which uses createChat instead of useChat . Each one threads the TSchema generic the same way: Net effect: in any of the four frameworks, with outputSchema: RecipeSchema, messages i .parts.find p = p.type === 'structured-output' .data resolves to Recipe | undefined. Default TData = unknown keeps every existing consumer that doesn't pass a schema source-compatible. @tanstack/ai-preact doesn't support outputSchema yet; that's tracked separately. The multi-turn pattern lights up any UI where: For a single round-trip one prompt, one typed object , use chat { outputSchema } https://tanstack.com/ai/docs/structured-outputs/one-shot , the non-streaming activity is simpler. For a streaming UI that progressively fills in one object the classic field-by-field form , use useChat { outputSchema } https://tanstack.com/ai/docs/structured-outputs/streaming and read partial / final, the new shape preserves that surface unchanged. Use multi-turn https://tanstack.com/ai/docs/structured-outputs/multi-turn when history is a feature, not a chore. The full recipe-builder UI ships in the ts-react-chat example https://github.com/TanStack/ai/tree/main/examples/ts-react-chat at /generations/structured-chat: cuisine-aware hero banners, streaming preview, multi-turn history, the lot. The docs walk through the pattern at structured-outputs/multi-turn https://tanstack.com/ai/docs/structured-outputs/multi-turn . If you already use useChat { outputSchema } , you don't need to change anything to get the new types — partial and final keep working. You opt into multi-turn the moment you walk messages instead of just reading the hook-level sugar.