Type-safe LLM outputs with Zod: stop guessing what the model returns.

A developer describes how to enforce type-safe LLM outputs using Zod schemas, preventing runtime errors from unexpected model responses. The approach covers defining schemas, integrating with Vercel AI SDK and Anthropic SDK, and implementing retry loops for parse failures.

I shipped a classifier to production in January. The prompt asked for JSON with a single category field. For three weeks it worked fine. Then the model started returning {"category":"bug","explanation":"this looks like a crash"} and the consumer threw a runtime error because it only expected one key. No schema change, no deploy. The model just decided to be helpful. Zod plus a bit of discipline around the parse step closes that gap. This tutorial walks through defining schemas for LLM output shapes, using them with the Vercel AI SDK and the raw Anthropic SDK, and building a retry loop that handles the cases where the model still gets it wrong. | Step | What | Why | |---|---|---| | Define Zod schema | Describe the shape you want | Single source of truth for your types | | Use generateText with Output.object | Vercel AI SDK path | Schema-enforced, provider-agnostic | | Use tool use with tool choice | Anthropic SDK path | Forces structured output without extra wrappers | | Parse and retry on failure | ZodError catches drift | Recovers without crashing callers | Most LLM tutorials show JSON.parse response and call it a day. The problem is that the model never agreed to your schema. Ask it to return {"category": "bug"} and it might return: {"category": "bug"} correct {"Category": "Bug"} wrong casing {"category": "bug", "confidence": 0.9} extra field {"error": "I cannot classify this"} helpful, but not your schema Without a parse step that actually validates the shape, every one of those paths silently corrupts downstream data. The fix is three lines of Zod plus one .safeParse call. Every technique in this article builds on that pattern, whether you use the Vercel AI SDK, the raw Anthropic SDK, or both. js import { z } from "zod"; const ClassifyResult = z.object { category: z.enum "bug", "feature", "question" , } ; type ClassifyResult = z.infer<typeof ClassifyResult ; // At runtime: const parsed = ClassifyResult.safeParse JSON.parse rawOutput ; if parsed.success { // parsed.error is a ZodError with field-level detail console.error "Shape violation:", parsed.error.issues ; } Install Zod 4 currently the stable major : npm install zod@^4.0.0 The core APIs z.object , z.string , z.enum , z.discriminatedUnion , z.infer all carry over from Zod 3. If you're already on Zod 3, the migration is largely additive for these use cases. LLM outputs tend to fall into three shapes: flat classifiers, richer extractors, and discriminated results where the model picks a branch. Zod handles all three. js import { z } from "zod"; export const SentimentSchema = z.object { sentiment: z.enum "positive", "negative", "neutral" , score: z.number .min -1 .max 1 , } ; export type Sentiment = z.infer<typeof SentimentSchema ; js export const InvoiceSchema = z.object { vendor: z.string , amount usd: z.number .positive , due date: z.string .regex /^\d{4}-\d{2}-\d{2}$/ , line items: z.array z.object { description: z.string , quantity: z.number .int .positive , unit price: z.number .positive , } , } ; export type Invoice = z.infer<typeof InvoiceSchema ; This is the shape to reach for when you want the model to pick one of three or more distinct output paths rather than a flat enum. js export const RoutingResult = z.discriminatedUnion "intent", z.object { intent: z.literal "search" , query: z.string , filters: z.array z.string .optional , } , z.object { intent: z.literal "create" , resource type: z.string , fields: z.record z.string , z.unknown , } , z.object { intent: z.literal "clarify" , question: z.string , } , ; export type RoutingResult = z.infer<typeof RoutingResult ; The discriminated union is strict: if intent is "search" , Zod knows to expect query , and a parse attempt with intent: "create" plus a query field fails cleanly. The Vercel AI SDK added schema-native structured output in recent versions. You pass a Zod schema through Output.object and the SDK handles the prompt scaffolding and parse step for you. js import { generateText, Output } from "ai"; import { anthropic } from "@ai-sdk/anthropic"; import { z } from "zod"; const SentimentSchema = z.object { sentiment: z.enum "positive", "negative", "neutral" , score: z.number .min -1 .max 1 , } ; async function analyzeSentiment text: string { const { output } = await generateText { model: anthropic "claude-sonnet-4-5-20251022" , output: Output.object { schema: SentimentSchema } , prompt: Analyze the sentiment of this text: "${text}" , } ; // output is typed as { sentiment: "positive" | "negative" | "neutral"; score: number } return output; } // Usage const result = await analyzeSentiment "The deploy went sideways at 3am." ; console.log result.sentiment ; // TypeScript knows this is the enum console.log result.score ; // TypeScript knows this is a number The return type flows from the schema without any casting. If the model returns something that does not match, the SDK throws before the result reaches your code. For streaming partial objects as they arrive: js import { streamText, Output } from "ai"; const { partialOutputStream } = streamText { model: anthropic "claude-sonnet-4-5-20251022" , output: Output.object { schema: InvoiceSchema } , prompt: "Extract the invoice details from this text: ...", } ; for await const partial of partialOutputStream { // partial is a Partial<Invoice as fields arrive console.log partial ; } Add an onError callback for stream errors since they arrive in-band rather than as thrown exceptions. If you use the Anthropic SDK directly and want schema-enforced output without the Vercel SDK wrapper, the reliable path is tool use with tool choice forced to your schema tool. The idea: define a "tool" whose input schema describes the JSON shape you want. Force the model to call that tool with tool choice: { type: "tool", name: "..." } . The model then returns a tool use block with structured input instead of free text. You parse that input with Zod. python import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; const client = new Anthropic { apiKey: process.env.ANTHROPIC API KEY } ; // 1. Define your Zod schema const ClassifyResult = z.object { category: z.enum "bug", "feature", "question" , confidence: z.number .min 0 .max 1 , reasoning: z.string , } ; type ClassifyResult = z.infer<typeof ClassifyResult ; // 2. Mirror the schema in JSON Schema for the tool definition const classifyTool = { name: "classify ticket", description: "Classify a support ticket into exactly one category with a confidence score.", input schema: { type: "object" as const, properties: { category: { type: "string", enum: "bug", "feature", "question" , description: "The category that best fits the ticket.", }, confidence: { type: "number", description: "Confidence score from 0 to 1.", }, reasoning: { type: "string", description: "One sentence explaining the classification.", }, }, required: "category", "confidence", "reasoning" , }, }; async function classifyTicket text: string : Promise<ClassifyResult { const response = await client.messages.create { model: "claude-haiku-4-5-20251001", max tokens: 512, tools: classifyTool , // Force the model to call this specific tool tool choice: { type: "tool", name: "classify ticket" }, messages: { role: "user", content: Classify this support ticket: "${text}" , }, , } ; // 3. Extract the tool use block from the response const toolUseBlock = response.content.find b = b.type === "tool use" ; if toolUseBlock || toolUseBlock.type == "tool use" { throw new Error "Model did not return a tool use block" ; } // 4. Validate with Zod const parsed = ClassifyResult.safeParse toolUseBlock.input ; if parsed.success { throw new Error Schema violation: ${JSON.stringify parsed.error.issues } ; } return parsed.data; } The tool choice parameter with type: "tool" is the key detail. Without it, the model may choose to answer in plain text. With it, the response always comes back as a structured tool use block. One practical note: you define the schema twice here, once in Zod and once in JSON Schema. For small schemas that duplication is tolerable. For larger ones, look at zod-to-json-schema on npm to generate the input schema from your Zod definition automatically. Even with forced tool use and schema prompting, models occasionally return output that fails validation. Network hiccups, context window pressure, and edge-case inputs all produce unexpected shapes. Build the retry loop before you need it. async function classifyWithRetry text: string, maxAttempts = 3 : Promise<ClassifyResult { let lastError: unknown; for let attempt = 1; attempt <= maxAttempts; attempt++ { try { return await classifyTicket text ; } catch err { lastError = err; console.warn classify attempt ${attempt} failed: , err ; if attempt < maxAttempts { // Small back-off: 500ms, 1000ms, ... await new Promise r = setTimeout r, attempt 500 ; } } } throw new Error classify failed after ${maxAttempts} attempts: ${lastError} ; } When the model returns a close-but-wrong shape, feeding the validation error back in a second call often works better than a blind retry. The model can see what it got wrong and correct it. async function classifyWithRepair text: string : Promise<ClassifyResult { // First attempt const response = await client.messages.create { model: "claude-haiku-4-5-20251001", max tokens: 512, tools: classifyTool , tool choice: { type: "tool", name: "classify ticket" }, messages: { role: "user", content: Classify: "${text}" } , } ; const toolBlock = response.content.find b = b.type === "tool use" ; const rawInput = toolBlock?.type === "tool use" ? toolBlock.input : null; const parsed = ClassifyResult.safeParse rawInput ; if parsed.success { return parsed.data; } // Repair attempt: show the model what it returned and what the schema expects const repairMessages = { role: "user" as const, content: Classify: "${text}" }, { role: "assistant" as const, content: response.content, }, { role: "user" as const, content: Your output did not match the schema. Validation errors: ${JSON.stringify parsed.error.issues }. Please call classify ticket again with a valid response. , }, ; const repairResponse = await client.messages.create { model: "claude-haiku-4-5-20251001", max tokens: 512, tools: classifyTool , tool choice: { type: "tool", name: "classify ticket" }, messages: repairMessages, } ; const repairBlock = repairResponse.content.find b = b.type === "tool use" ; const repaired = ClassifyResult.safeParse repairBlock?.type === "tool use" ? repairBlock.input : null ; if repaired.success { throw new Error repair attempt failed: ${JSON.stringify repaired.error.issues } ; } return repaired.data; } The repair pattern costs one extra call but recovers most edge cases without manual intervention. js import { z } from "zod"; export const IntentSchema = z.object { intent: z.enum "search", "create", "delete", "status", "help" , confidence: z.number .min 0 .max 1 , extracted entity: z.string .optional , } ; export type Intent = z.infer<typeof IntentSchema ; // JSON Schema for Anthropic tool use export const intentToolSchema = { type: "object" as const, properties: { intent: { type: "string", enum: "search", "create", "delete", "status", "help" , }, confidence: { type: "number" }, extracted entity: { type: "string" }, }, required: "intent", "confidence" , }; js export const ContactExtractSchema = z.object { name: z.string , email: z.string .email .optional , phone: z.string .optional , company: z.string .optional , notes: z.string .optional , } ; export type ContactExtract = z.infer<typeof ContactExtractSchema ; // JSON Schema for Anthropic tool use export const contactExtractToolSchema = { type: "object" as const, properties: { name: { type: "string", description: "Full name of the contact" }, email: { type: "string", description: "Email address if present" }, phone: { type: "string", description: "Phone number if present" }, company: { type: "string", description: "Company or organization if mentioned" }, notes: { type: "string", description: "Any other relevant details" }, }, required: "name" , }; Usage with the raw Anthropic SDK: js const extractTool = { name: "extract contact", description: "Extract contact information from the provided text.", input schema: contactExtractToolSchema, }; const response = await client.messages.create { model: "claude-haiku-4-5-20251001", max tokens: 512, tools: extractTool , tool choice: { type: "tool", name: "extract contact" }, messages: { role: "user", content: Extract contact info from: "Hi, I'm Sarah Chen at Acme Corp. Reach me at sarah@acme.io" , }, , } ; const block = response.content.find b = b.type === "tool use" ; const result = ContactExtractSchema.safeParse block?.type === "tool use" ? block.input : null ; if result.success { console.log result.data.name ; // "Sarah Chen" console.log result.data.email ; // "sarah@acme.io" } JSON.parse without validation is a time bomb. The model will eventually return a shape you did not expect, and the failure mode is silent data corruption, not a loud error you can catch immediately. The fix costs two things: a Zod schema which you should write anyway for TypeScript types and a .safeParse call instead of a raw JSON.parse . The Vercel AI SDK with Output.object handles the wiring for you. The raw Anthropic SDK with tool choice forced to a specific tool gives you the same guarantee with one extra setup step. The retry and repair patterns are insurance. In practice, with tool choice forced, parse failures happen in under 1% of calls for well-formed schemas. The 1% still matters when you are running 50,000 classifications a day. What shape does your most chaotic LLM output have right now? Drop it in the comments. GDS K S · thegdsks.com https://thegdsks.com · follow on X @thegdsks https://x.com/thegdsks A Zod schema is the contract the model never gets to break.