Skip to main content

Structured Output

Intermediate
What you'll learn
  • Explain why schema-enforced output beats prompting for JSON and hoping
  • Provide a JSON Schema and parse the response into a typed object (Pydantic / Zod)
  • Tell structured output apart from tool use by intent, not by mechanism
  • Apply the four tips for tight, reliable schemas
  • Pick the right tool with a one-question rule of thumb

When Claude's output feeds other software, you need reliable structure — valid JSON matching a known shape, every time. Don't rely on "respond in JSON" and hope; use the platform's structured-output support.

This lesson walks you from why prompt-and-pray fails to how to enforce a schema and parse it into a typed object — and how to tell structured output apart from tool use when they look identical. Work through it top to bottom, then test yourself with the quiz near the end.

The reliable way​

Provide a JSON Schema for the output and let the API/SDK enforce it, then parse into a typed object (e.g. Pydantic in Python, Zod in TypeScript). The SDK parse helpers hand you a typed result instead of a string you have to JSON.parse and validate yourself.

Guided walkthrough1 of 3
  1. Model the output you need as a JSON Schema — in Python via a Pydantic BaseModel, in TypeScript via a Zod schema.
# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

Want a concrete request to adapt? Here is the shape of what you hand the model — replace the model with your own schema.

Ask for schema-conforming output

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

Why not just prompt for JSON?​

You can ask for JSON in the prompt, and for simple cases it works — but it can drift: stray prose, a trailing comma, a missing field. Schema-enforced output removes that class of bug, which matters the moment a downstream system depends on it.

Watch out
  • Prompted JSON works in demos and breaks in production: the failure shows up only when a downstream system parses it.
  • Three classic drifts to watch for: stray prose around the JSON, a trailing comma, a missing required field.

Structured output vs. tool use​

Both features hand the model a JSON Schema, so they look alike — and people pick the wrong one. The difference is intent, not mechanism:

Structured outputTool use
What you wantThe final answer, in a fixed shapeThe model to invoke a capability (call a function, fetch data, take an action)
Who consumes itYour code, directlyYour code runs the tool, then feeds the result back to the model
Turn shapeOne response, doneA loop: model asks, you execute, model continues
Typical useExtraction, classification, parsingAgents, live lookups, side effects

A quick rule of thumb:

If the JSON is the deliverable, use structured output. If the JSON is the model asking your code to do something, that's tool use. Agents often use both: tools to act, structured output to return a clean final result.

Tips​

Pro tip
  • Keep schemas tight — use enums for fixed choices; mark required fields.
  • Describe fields — field descriptions guide the model like mini-prompts.
  • Validate anyway at the boundary — defensive parsing is cheap insurance.
  • For extraction tasks, structured output + a clear schema beats freeform every time.
Key takeaways
  • Hand the API/SDK a JSON Schema and parse into a typed object — don't prompt-and-pray.
  • Prompting for JSON can drift (stray prose, trailing comma, missing field); schema enforcement removes that bug class.
  • Structured output vs. tool use differ by intent: the JSON IS the answer vs. the JSON requests an action.
  • Tight schemas, described fields, and boundary validation make extraction and classification reliable.

Lock in the terms​

Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 5

Check yourself

0/4
  1. What is the reliable way to get structured JSON from Claude?
  2. Why is prompting for JSON risky once a downstream system depends on it?
  3. What actually distinguishes structured output from tool use?
  4. Which is sound advice for designing schemas?

Next​