Practical Guide to Output Parsers: Ensuring Stable JSON from LLMs

01 Identify the Problem

LLM JSON output failures fall into three categories: format errors (e.g., missing quotes), missing fields, and incorrect types (e.g., a string where a number is expected). Each failure requires a distinct remedy.

02 Modern Solution: withStructuredOutput + Zod

Models that support Function Calling (OpenAI, Claude, Gemini, etc.) can use withStructuredOutput to return structured data directly, avoiding format errors. Define a Zod schema, bind it to the model, and invoke the model to obtain a TypeScript‑type‑safe result. The .describe() calls become the function‑calling parameter descriptions, improving accuracy.

import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

// 1. Define the schema
const ProductSchema = z.object({
  name: z.string().describe("商品名称"),
  price: z.number().describe("价格，单位元"),
  category: z.enum(["电子", "服装", "食品"]).describe("商品类别"),
  inStock: z.boolean().describe("是否有库存"),
  tags: z.array(z.string()).optional().describe("商品标签列表"),
});

// 2. Bind to the model
const model = new ChatOpenAI({ model: "gpt-4o-mini", temperature: 0 });
const structuredModel = model.withStructuredOutput(ProductSchema, { name: "product_extractor" });

// 3. Invoke
const result = await structuredModel.invoke("帮我提取这个商品信息：新款 iPhone 16 Pro，5999元，电子产品，现货，标签：苹果、手机、5G");
console.log(result);

The resulting object has correctly typed fields (e.g., price is a number, inStock is a boolean) without manual conversion.

03 Assemble the Logic with LCEL

The withStructuredOutput call returns a Runnable that can be piped into a LangChain Expression Language (LCEL) chain. The article shows a sentiment‑analysis chain that extracts sentiment, score, keywords, and summary from user reviews, both for single and batch inputs.

import { ChatPromptTemplate } from "@langchain/core/prompts";

const SentimentSchema = z.object({
  sentiment: z.enum(["正面", "负面", "中性"]).describe("评论的整体情感倾向"),
  score: z.number().min(0).max(10).describe("情感强度评分，0-10"),
  keywords: z.array(z.string()).describe("触发该情感的关键词"),
  summary: z.string().describe("一句话总结评论观点"),
});

const sentimentModel = model.withStructuredOutput(SentimentSchema, { name: "sentiment_analyzer" });
const sentimentChain = ChatPromptTemplate.fromMessages([
  ["system", "你是一个专业的用户评论分析师。分析用户评论的情感倾向，提取关键信息。"],
  ["human", "请分析这条评论：
{review}"],
]).pipe(sentimentModel);

const analysis = await sentimentChain.invoke({ review: "这款耳机音质超棒，戴着很舒服，就是价格有点贵，但物有所值！" });
console.log(analysis);

04 Fallback for Models Without Function Calling

When using older APIs or locally deployed open‑source models (Llama, Qwen, etc.), withStructuredOutput is unavailable. In this case, employ JsonOutputParser together with a system prompt generated by parser.getFormatInstructions() to force the model to emit pure JSON.

import { JsonOutputParser } from "@langchain/core/output_parsers";
import { ChatPromptTemplate } from "@langchain/core/prompts";

type ResumeInfo = { name: string; experience_years: number; skills: string[]; current_company: string; };
const parser = new JsonOutputParser<ResumeInfo>();
const prompt = ChatPromptTemplate.fromMessages([
  ["system", `你是一个简历解析助手。从简历文本中提取关键信息。
{format_instructions}

重要：只输出 JSON，不要有任何额外文字。`],
  ["human", "简历内容：
{resume_text}"],
]).partial({ format_instructions: parser.getFormatInstructions() });

const chain = prompt.pipe(model).pipe(parser);
const result = await chain.invoke({ resume_text: `张伟，5年前端开发经验
现任职于字节跳动，前端工程师
技能：React, TypeScript, Node.js, Vue` });
console.log(result);

05 Robustness: Handling Parse Failures

If JsonOutputParser throws on malformed output, two strategies are offered:

Option 1: Wrap the base parser with OutputFixingParser, which detects errors, asks the LLM to correct them, and re‑parses.

Option 2: Write explicit try/catch logic with a fallback value for non‑JSON errors.

import { OutputFixingParser } from "langchain/output_parsers";
import { StructuredOutputParser } from "@langchain/core/output_parsers";
import { z } from "zod";

const baseParser = StructuredOutputParser.fromZodSchema(z.object({
  title: z.string().describe("文章标题"),
  wordCount: z.number().describe("字数"),
  readTime: z.number().describe("预计阅读分钟数"),
}));
const fixingParser = OutputFixingParser.fromLLM(model, baseParser);

const brokenOutput = `{
  "title": "如何学好 TypeScript",
  "wordCount": "3500", // string instead of number
  // missing readTime
}`;
const fixed = await fixingParser.parse(brokenOutput);
console.log(fixed);

06 Advanced Zod: Nested Structures

Real‑world JSON often contains deep nesting. The article defines AddressSchema, OrderItemSchema, and OrderSchema to extract e‑commerce order details, demonstrating validation rules such as .min(), .regex(), and .positive(). The resulting TypeScript object is fully type‑safe.

const AddressSchema = z.object({
  province: z.string().describe("省份"),
  city: z.string().describe("城市"),
  detail: z.string().describe("详细地址"),
});

const OrderItemSchema = z.object({
  productName: z.string().describe("商品名称"),
  quantity: z.number().int().positive().describe("购买数量"),
  unitPrice: z.number().positive().describe("单价"),
});

const OrderSchema = z.object({
  orderId: z.string().describe("订单编号，格式如 ORD-20250408-001"),
  customer: z.object({ name: z.string().describe("买家姓名"), phone: z.string().regex(/^1[3-9]\d{9}$/).describe("手机号，11位") }),
  shippingAddress: AddressSchema.describe("收货地址"),
  items: z.array(OrderItemSchema).min(1).describe("订单商品列表"),
  totalAmount: z.number().positive().describe("订单总金额"),
  status: z.enum(["待支付", "已支付", "已发货", "已完成", "已退款"]).describe("订单状态"),
  remark: z.string().optional().describe("买家备注"),
});

const orderExtractor = model.withStructuredOutput(OrderSchema, { name: "order_extractor" });
const order = await orderExtractor.invoke(`从以下客服对话中提取订单信息：
客户说：我的订单 ORD-20250408-001 还没发货，我买了2件Nike T恤，每件299，
发到上海市浦东新区张江路100号，联系方式 13812345678，备注要黑色款。`);
console.log(order.customer.phone); // "13812345678"
console.log(order.items[0].unitPrice); // 299

07 Streaming JSON Output

For long‑text scenarios, waiting for the full LLM response can be slow. JsonOutputParser can parse incrementally as tokens arrive, and withStructuredOutput also supports streaming, yielding partially filled objects.

const streamParser = new JsonOutputParser();
const streamChain = ChatPromptTemplate.fromMessages([
  ["system", "生成一个包含10个元素的 JSON 数组，每个元素包含 id 和 name 字段。直接输出 JSON，不要 markdown 代码块。"],
  ["human", "请生成"],
]).pipe(model).pipe(streamParser);

for await (const chunk of await streamChain.stream({})) {
  console.log("当前已解析:", JSON.stringify(chunk));
}

08 Selection Decision Tree

The article concludes with a decision diagram:

If the model supports Function Calling → use withStructuredOutput + Zod (most stable, type‑safe).

If not, choose between JsonOutputParser (with streaming if needed) or a prompt‑engineered StructuredOutputParser based on whether streaming is required.

In production, always add fault‑tolerance via OutputFixingParser or explicit try/catch fallback.

These guidelines help developers reliably obtain structured JSON from LLMs across diverse environments.