Structured Output from LLMs: How to Get Guaranteed JSON Every Time

// Schema: { type: "object", properties: { age: { type: "integer" } } }
// The model is generating: {"age": |
//                                    ^ cursor here

// Without constrained decoding:
// All ~100K tokens are valid. Model might produce:
//   "twenty-five"  (string, not integer)
//   25.5           (float, not integer)
//   null           (null, not integer)

// With constrained decoding:
// Only digit tokens (0-9) and closing tokens are valid.
// Model MUST produce a valid integer.
// Token mask: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + structural tokens
// Result: 25 (guaranteed integer)

import OpenAI from "openai";

const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [
    { role: "user", content: "Extract: John Smith, john@acme.com, VP Engineering" }
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "contact",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          email: { type: "string" },
          title: { type: "string" },
          department: { type: ["string", "null"] }
        },
        required: ["name", "email", "title", "department"],
        additionalProperties: false
      }
    }
  }
});

const contact = JSON.parse(response.choices[0].message.content);
// { name: "John Smith", email: "john@acme.com",
//   title: "VP Engineering", department: null }
// Guaranteed to match schema. No try/catch needed.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-5-20250514",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Extract: John Smith, john@acme.com, VP Engineering"
    }
  ],
  output_config: {
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          email: { type: "string" },
          title: { type: "string" },
          department: { type: ["string", "null"] }
        },
        required: ["name", "email", "title", "department"],
        additionalProperties: false
      }
    }
  }
});

const textBlock = response.content.find(b => b.type === "text");
const contact = JSON.parse(textBlock.text);
// Schema-compliant. Same guarantee as OpenAI strict mode.

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Extract: John Smith, john@acme.com, VP Engineering",
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: {
      type: "object",
      properties: {
        name: { type: "string" },
        email: { type: "string" },
        title: { type: "string" },
        department: { type: ["string", "null"] }
      },
      required: ["name", "email", "title", "department"]
    }
  }
});

const contact = JSON.parse(response.text);

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

// Define the schema once
const CodeReview = z.object({
  file: z.string().describe("The file path reviewed"),
  issues: z.array(z.object({
    line: z.number().int().describe("Line number"),
    severity: z.enum(["error", "warning", "info"]),
    message: z.string().describe("Description of the issue"),
    suggestion: z.string().describe("Suggested fix")
  })),
  summary: z.string().describe("One-line summary of findings"),
  approved: z.boolean()
});

// TypeScript knows the return type
type CodeReviewResult = z.infer<typeof CodeReview>;

const openai = new OpenAI();
const completion = await openai.chat.completions.parse({
  model: "gpt-5",
  messages: [
    { role: "system", content: "Review the following code for bugs and style issues." },
    { role: "user", content: fileContents }
  ],
  response_format: zodResponseFormat(CodeReview, "code_review")
});

// completion.choices[0].message.parsed is typed as CodeReviewResult
const review = completion.choices[0].message.parsed;
console.log(review.issues.length); // TypeScript autocomplete works
console.log(review.approved);      // boolean, guaranteed

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

const ContactSchema = z.object({
  name: z.string(),
  email: z.string(),
  company: z.string(),
  role: z.enum(["engineer", "manager", "executive", "other"])
});

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-4-5-20250514",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Extract contact: Jane Doe, CTO at Stripe, jane@stripe.com" }
  ],
  output_format: zodOutputFormat(ContactSchema, "contact")
});

// SDK parses and validates automatically
const contact = JSON.parse(
  response.content.find(b => b.type === "text")?.text ?? "{}"
);

import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const { object } = await generateObject({
  model: openai("gpt-5"),
  schema: z.object({
    tasks: z.array(z.object({
      title: z.string().describe("Short task title"),
      priority: z.enum(["high", "medium", "low"]),
      estimatedHours: z.number().describe("Estimated hours to complete"),
      dependencies: z.array(z.string()).describe("Task titles this depends on")
    })),
    totalHours: z.number()
  }),
  prompt: "Break down this project into tasks: Build a REST API for user management"
});

// object is fully typed. No JSON.parse. No validation code.
// The AI SDK handles schema conversion, API call, and parsing.
for (const task of object.tasks) {
  console.log(`[${task.priority}] ${task.title} - ${task.estimatedHours}h`);
}

from pydantic import BaseModel
from openai import OpenAI

class Issue(BaseModel):
    line: int
    severity: str  # "error" | "warning" | "info"
    message: str
    suggestion: str

class CodeReview(BaseModel):
    file: str
    issues: list[Issue]
    summary: str
    approved: bool

client = OpenAI()
completion = client.beta.chat.completions.parse(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "Review the code for bugs."},
        {"role": "user", "content": file_contents}
    ],
    response_format=CodeReview
)

review = completion.choices[0].message.parsed
# review is a CodeReview instance with full type hints
print(f"{len(review.issues)} issues found, approved: {review.approved}")

const tools = [
  {
    type: "function",
    name: "read_file",
    strict: true,
    description: "Read the contents of a file at the given path",
    parameters: {
      type: "object",
      properties: {
        path: { type: "string", description: "File path relative to project root" },
        start_line: { type: ["integer", "null"], description: "First line to read (1-indexed). Null for start of file." },
        end_line: { type: ["integer", "null"], description: "Last line to read. Null for end of file." }
      },
      required: ["path", "start_line", "end_line"],
      additionalProperties: false
    }
  },
  {
    type: "function",
    name: "write_file",
    strict: true,
    description: "Write content to a file, creating it if it doesn't exist",
    parameters: {
      type: "object",
      properties: {
        path: { type: "string", description: "File path relative to project root" },
        content: { type: "string", description: "The full file content to write" }
      },
      required: ["path", "content"],
      additionalProperties: false
    }
  },
  {
    type: "function",
    name: "search_code",
    strict: true,
    description: "Search the codebase using a regex pattern. Returns matching lines with file paths and line numbers.",
    parameters: {
      type: "object",
      properties: {
        pattern: { type: "string", description: "Regex pattern to search for" },
        file_glob: { type: ["string", "null"], description: "Glob to filter files, e.g. '*.ts'. Null for all files." },
        max_results: { type: "integer", description: "Maximum number of matches to return" }
      },
      required: ["pattern", "file_glob", "max_results"],
      additionalProperties: false
    }
  }
];

{
  type: "function",
  name: "edit_file",
  strict: true,
  description: "Apply a targeted edit to a file by replacing old_text with new_text",
  parameters: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "File path relative to project root"
      },
      old_text: {
        type: "string",
        description: "The exact text to find and replace. Must match uniquely."
      },
      new_text: {
        type: "string",
        description: "The replacement text"
      }
    },
    required: ["path", "old_text", "new_text"],
    additionalProperties: false
  }
}

const DispatchSchema = z.object({
  subtask: z.string().describe("Clear description of what the subagent should do"),
  agent_type: z.enum(["coder", "reviewer", "tester", "researcher"]),
  context: z.object({
    files: z.array(z.string()).describe("File paths relevant to the subtask"),
    constraints: z.array(z.string()).describe("Rules the subagent must follow"),
    prior_results: z.string().describe("Summary of work done so far")
  }),
  expected_output: z.enum(["code_edit", "review_report", "test_results", "analysis"]),
  timeout_seconds: z.number().int().describe("Max time before the subtask is killed")
});

// The orchestrator model generates this schema,
// your application routes to the correct subagent,
// and the subagent returns its own structured result.

// Define as a tool in your agent
const fastApplyTool = {
  type: "function",
  name: "apply_code_edit",
  strict: true,
  description: "Apply a code edit using Morph Fast Apply. Faster and more accurate than full-file rewrites.",
  parameters: {
    type: "object",
    properties: {
      original_code: { type: "string", description: "Current file contents" },
      edit_snippet: { type: "string", description: "The edit to apply (diff, snippet, or description)" },
      filename: { type: "string", description: "Filename for language detection" }
    },
    required: ["original_code", "edit_snippet", "filename"],
    additionalProperties: false
  }
};

// Execute the tool call
async function executeFastApply(args: {
  original_code: string;
  edit_snippet: string;
  filename: string;
}) {
  const response = await fetch("https://api.morphllm.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.MORPH_API_KEY}`
    },
    body: JSON.stringify({
      model: "morph-v3-fast",
      messages: [
        { role: "user", content: args.edit_snippet }
      ],
      original_code: args.original_code,
      filename: args.filename
    })
  });
  const data = await response.json();
  return data.choices[0].message.content; // The edited file
}