
Structured Output with Zod: Getting Reliable JSON from LLMs in TypeScript
By Ghazi Khan | Nov 16, 2026 - 10 min read
You ask a model to "return JSON with a title and a severity", and it works in every demo. Then production traffic arrives: one response is wrapped in a markdown code fence, another says "severity": "urgent" when your union only allows four values, and a third leaves out a field your component reads without a check. Structured output with Zod fixes this by making the model's answer pass the same kind of validation you already use for forms and API responses.
This post explains how structured output works under the hood, then builds a bug report triage feature in TypeScript with the AI SDK 7 APIs: a typed result on the server, a retry for invalid output, and a React UI that renders the object while it streams.
The concept: treat the model like an untrusted API
You already know this pattern. When your React app calls a third-party API, you do not trust the response type just because the docs say so. You validate it at the boundary with Zod, and only then let it into your components:
const user = userSchema.parse(await res.json()); // throws if the shape is wrong
An LLM is the least trustworthy API you will ever call. Its output is text sampled one token at a time, so "valid JSON in the right shape" is a likelihood, not a guarantee. Structured output turns that likelihood into a contract in two places:
- Before generation. Your Zod schema is converted to JSON Schema and sent to the provider. Providers with native structured output support use it to steer, and in strict modes constrain, what the model can produce.
- After generation. The SDK parses the text and validates it against the same Zod schema. You get a typed object, or a specific error you can handle.
Think of it as react-hook-form with a Zod resolver, except the user filling the form is the model.
Diagram100%flowchart LR A["Zod schema"] --> B["JSON Schema sent with the request"] B --> C["Provider generates text, guided by the schema"] C --> D["SDK parses JSON"] D --> E{"Zod validation"} E -->|valid| F["Typed output"] E -->|invalid| G["NoObjectGeneratedError"]visualized by
Here is how the common approaches compare:
| Approach | Valid JSON guaranteed? | Shape checked? | Typed in TS? |
|---|---|---|---|
"Reply in JSON" in the prompt plus JSON.parse | No | No | Only by a cast that proves nothing |
Output.json() | Parsed, not shaped | No | unknown-like |
Output.object({ schema }) | Parsed and validated | Yes, by Zod | Yes, inferred from the schema |
The structured output API in AI SDK 7
If you follow older tutorials you will see generateObject and streamObject. Those were deprecated in AI SDK 6 and will be removed in a future version. The current way is to pass an output setting to generateText or streamText. AI SDK 7 also removed the old experimental_output option, so output is the only name.
| Helper | Use it when | Result |
|---|---|---|
Output.object({ schema }) | You need one object with a known shape | Validated object |
Output.array({ element }) | You need a list, possibly streamed item by item | Array of validated elements |
Output.choice({ options }) | Classification into fixed labels | One of the strings |
Output.json() | Any JSON, you validate it yourself | Parsed JSON |
Output.text() | Plain text (the default) | String |
Build it: a typed bug report triager
Install the packages. AI SDK 7 needs Node.js 22 or later and accepts Zod ^3.25.76 or ^4.1.8 as a peer dependency.
npm i ai @ai-sdk/react zod
npm i -D tsx
The examples use the Vercel AI Gateway, which is the default provider in AI SDK 7, so a plain model string works once AI_GATEWAY_API_KEY is in .env.local. Any provider package works the same way.
Step 1: the schema is the prompt
Every field name, enum and .describe() call becomes part of the JSON Schema the model sees. Write it like documentation for a new teammate.
// lib/bug-schema.ts
import { z } from 'zod';
export const bugReportSchema = z.object({
title: z.string().describe('Short issue title, under 80 characters'),
severity: z.enum(['low', 'medium', 'high', 'critical']),
area: z.enum(['ui', 'performance', 'accessibility', 'data', 'auth']),
component: z
.string()
.nullable()
.describe('React component named in the report, otherwise null'),
browser: z.string().nullable().describe('Browser and version if mentioned'),
steps: z
.array(z.string())
.describe('Steps to reproduce, one user action per item'),
});
export type BugReport = z.infer<typeof bugReportSchema>;
Notice .nullable() instead of .optional(). Strict structured output modes, such as OpenAI's, require every property to be present, and you model "no value" as a union with null. The OpenAI provider in the AI SDK has used strict JSON Schema by default since version 6. A nullable field also forces the model to make an explicit decision instead of silently skipping the key.
Step 2: generate a typed object, with one retry
// lib/triage.ts
import { generateText, NoObjectGeneratedError, Output } from 'ai';
import { bugReportSchema, type BugReport } from './bug-schema';
const MODEL = 'anthropic/claude-sonnet-5.5';
const INSTRUCTIONS =
'You triage bug reports for a React web app. Use only facts from the report.';
export async function triageBugReport(
report: string,
maxAttempts = 2,
): Promise<BugReport> {
let prompt = report;
for (let attempt = 1; ; attempt++) {
try {
const { output } = await generateText({
model: MODEL,
instructions: INSTRUCTIONS,
output: Output.object({ name: 'BugReport', schema: bugReportSchema }),
prompt,
});
return output; // typed as BugReport
} catch (error) {
if (!NoObjectGeneratedError.isInstance(error) || attempt >= maxAttempts) {
throw error;
}
console.warn('Invalid structured output', {
cause: error.cause,
usage: error.usage,
});
prompt = `${report}\n\nYour previous answer failed validation: ${String(
error.cause,
)}. Return an object that matches the schema exactly.`;
}
}
}
Three things matter here. output is fully typed from the schema, with no cast. NoObjectGeneratedError is the specific error for "the model answered, but not in a valid shape", and it carries the raw text, the cause and the token usage, so you can log what went wrong and what it cost. Anything else (network errors, rate limits) is rethrown untouched, because retrying with a different prompt will not fix those. Keep retries to one or two, since every attempt is billed.
Try it from Node before you touch React:
// scripts/triage.ts
import { triageBugReport } from '../lib/triage';
const report = `On Safari 18 the Pay button in CartSummary does nothing
after I apply a coupon. Clicking twice shows a spinner forever.`;
const issue = await triageBugReport(report);
console.log(issue.severity, issue.component, issue.steps);
Run it with node --env-file=.env.local --import tsx scripts/triage.ts.
Step 3: stream the object into React
A full object can take a few seconds. With streamText, the same output setting gives you partial objects as they arrive, and useObject in @ai-sdk/react turns that stream into state.
// app/api/triage/route.ts
import { createTextStreamResponse, Output, streamText, toTextStream } from 'ai';
import { bugReportSchema } from '@/lib/bug-schema';
export async function POST(req: Request) {
const report: string = await req.json();
const result = streamText({
model: 'anthropic/claude-sonnet-5.5',
instructions: 'You triage bug reports for a React web app.',
output: Output.object({ schema: bugReportSchema }),
prompt: report,
});
return createTextStreamResponse({
stream: toTextStream({ stream: result.stream }),
});
}
// app/triage/page.tsx
'use client';
import { useObject } from '@ai-sdk/react';
import { bugReportSchema } from '@/lib/bug-schema';
export default function TriagePage() {
const { object, submit, isLoading, error, stop } = useObject({
api: '/api/triage',
schema: bugReportSchema,
});
return (
<section>
<button
disabled={isLoading}
onClick={() => submit('Pay button dead on Safari after coupon')}>
Triage
</button>
{isLoading && <button onClick={stop}>Stop</button>}
{error && <p role='alert'>Could not triage this report.</p>}
<h2>{object?.title ?? 'Waiting for title...'}</h2>
<p>Severity: {object?.severity ?? '...'}</p>
<ol>
{object?.steps?.map((step, i) => (
<li key={i}>{step}</li>
))}
</ol>
</section>
);
}
Every access uses optional chaining because object is a deep partial while streaming: steps may exist with two of its five items, and title may be half a sentence. Partial objects cannot be validated against the schema, so treat them as a preview and only act on the final value.
Diagram100%sequenceDiagram participant UI as useObject participant API as Route Handler participant M as Model UI->>API: POST report API->>M: streamText with Output.object M-->>API: JSON tokens API-->>UI: text stream UI->>UI: parse partial JSON, re-render M-->>API: final token API-->>UI: stream ends, full object validatedvisualized by
Step 4: lists and labels
Two smaller helpers cover a lot of real features. Output.choice is the cleanest way to classify:
const { output: kind } = await generateText({
model: 'anthropic/claude-sonnet-5.5',
output: Output.choice({ options: ['bug', 'feature-request', 'question'] }),
prompt: report,
});
Output.array with elementStream yields each element only once it is complete and validated, which is ideal for rendering a list without half-filled cards:
const result = streamText({
model: 'anthropic/claude-sonnet-5.5',
output: Output.array({ element: bugReportSchema, maxItems: 10 }),
prompt: `Split these QA notes into separate issues:\n${qaNotes}`,
});
for await (const issue of result.elementStream) {
console.log(issue.severity, issue.title);
}
If the model goes past maxItems, the element stream errors before the extra element and the final output promise rejects, so wrap it in the same error handling as Step 2.
Common mistakes
- Prompting for JSON and calling
JSON.parse. Code fences, trailing prose and wrong enum values all slip through. Fix: useOutput.objectso parsing and validation happen in one place, and stop copyinggenerateObjectfrom older tutorials. - Using
.optional()with strict providers. Strict JSON Schema modes reject schemas where properties are not all required, or the model leaves keys out. Fix: use.nullable()and rendernullexplicitly. - Expecting
.refine()or.transform()to guide the model. These run in JavaScript and have no JSON Schema equivalent, so the model never sees them. It only learns the rule when validation fails, which costs a retry. Fix: express rules as enums and.describe()text, and keep refinements for checks you can afford to fail on. - Acting on partial objects. A streamed
severityof'cri'is not a value you should save or trigger alerts from. Fix: render partials as a preview, and persist only the final validated output (or useelementStreamfor lists). - Mixing tools and structured output without enough steps. Generating the structured output counts as a step, so a tool call can use up the only step and leave no output. Fix: set
stopWhen: isStepCount(n)with room for the tool calls plus the final answer.
Interview angle
Structured output comes up as a design question: "the model sometimes returns broken JSON, how do you make this reliable?" A strong answer covers both layers (schema sent to the provider, validation after), explains nullable versus optional for strict modes, and describes a bounded retry that only fires on validation errors. Practise with the structured output interview questions.
What's next
On Thursday, the case study How an AI Code Review Bot Turns a PR into Inline Comments puts this into a real system: a diff goes in, a validated array of comments with file paths and line numbers comes out, and each one lands on the right line of the PR. Next week we move from shaped answers to actions, with tool calling and the agent loop.
Conclusion
Reliable JSON from an LLM is not a prompt trick. It is the same boundary validation you already do for any untrusted API, with the schema doing double duty as instructions. Write the schema like documentation, use .nullable() for missing values, catch NoObjectGeneratedError specifically, and treat streamed partials as a preview. Do that, and the model's output becomes something your TypeScript can depend on.
Advertisement
Ready to practice?
Test your skills with our interactive UI challenges and build your portfolio.
Start Coding Challenge