Search IOCombats

Search challenges, guides, questions and articles

Structured Output with Zod: Getting Reliable JSON from LLMs in TypeScript
aizodstructured outputvercel ai sdktypescriptreact

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:

  1. 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.
  2. 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.

Diagram
100%
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 byIOCombats

Here is how the common approaches compare:

ApproachValid JSON guaranteed?Shape checked?Typed in TS?
"Reply in JSON" in the prompt plus JSON.parseNoNoOnly by a cast that proves nothing
Output.json()Parsed, not shapedNounknown-like
Output.object({ schema })Parsed and validatedYes, by ZodYes, 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.

HelperUse it whenResult
Output.object({ schema })You need one object with a known shapeValidated object
Output.array({ element })You need a list, possibly streamed item by itemArray of validated elements
Output.choice({ options })Classification into fixed labelsOne of the strings
Output.json()Any JSON, you validate it yourselfParsed 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.

Diagram
100%
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 validated
visualized byIOCombats

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

  1. Prompting for JSON and calling JSON.parse. Code fences, trailing prose and wrong enum values all slip through. Fix: use Output.object so parsing and validation happen in one place, and stop copying generateObject from older tutorials.
  2. 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 render null explicitly.
  3. 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.
  4. Acting on partial objects. A streamed severity of '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 use elementStream for lists).
  5. 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