Claude Structured Outputs and JSON Mode: Complete Guide (2026)
The most reliable way to get structured JSON from Claude is to use tool use (function calling) with a defined JSON schema — Claude will always return valid JSON matching your schema when you define an output tool. For simpler cases, instructing Claude to respond with JSON in the system prompt combined with json.loads() validation also works, but tool use is more reliable in production. This guide covers both approaches with working Python code.
Why Structured Outputs Matter
Unstructured text responses are hard to parse reliably. When you're building pipelines that feed Claude's output into databases, APIs, or UI components, you need predictable structure. Two problems arise without it:
- Parsing failures: Claude adds explanatory text around JSON, breaking
json.loads() - Schema drift: Field names or types vary between runs
Both problems are solved by the tool use approach.
Method 1: Tool Use (Recommended)
Define an output "tool" that represents your desired JSON schema. Claude will call this tool to return structured output:
import anthropic
import json
client = anthropic.Anthropic()
# Define the output schema as a tool
output_tool = {
"name": "extract_article_data",
"description": "Extract structured data from the article",
"input_schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Article title"
},
"summary": {
"type": "string",
"description": "One-sentence summary"
},
"topics": {
"type": "array",
"items": {"type": "string"},
"description": "Main topics covered"
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"],
"description": "Overall sentiment"
},
"word_count": {
"type": "integer",
"description": "Approximate word count"
}
},
"required": ["title", "summary", "topics", "sentiment"]
}
}
article_text = """
Claude 3.5 Sonnet shows impressive gains in coding benchmarks,
outperforming GPT-4o on HumanEval by 8 points. The model is
particularly strong at multi-step reasoning tasks...
"""
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[output_tool],
tool_choice={"type": "tool", "name": "extract_article_data"}, # Force the tool
messages=[
{"role": "user", "content": f"Extract data from this article:\n\n{article_text}"}
]
)
# Extract the structured output
tool_use_block = next(b for b in response.content if b.type == "tool_use")
structured_data = tool_use_block.input
print(json.dumps(structured_data, indent=2))
Output:
{
"title": "Claude 3.5 Sonnet Coding Benchmark Results",
"summary": "Claude 3.5 Sonnet outperforms GPT-4o on HumanEval by 8 points.",
"topics": ["benchmarks", "coding", "model comparison", "reasoning"],
"sentiment": "positive",
"word_count": 42
}
The key is tool_choice={"type": "tool", "name": "your_tool_name"} — this forces Claude to call the specified tool, guaranteeing structured output.
Method 2: JSON Instruction in System Prompt
For simpler cases or when you need more flexibility:
import json
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
system="""You always respond with valid JSON only.
No explanation, no markdown code blocks, just the raw JSON object.
Never include any text before or after the JSON.""",
messages=[
{"role": "user", "content": """
Extract the following from this text as JSON:
- name (string)
- email (string)
- company (string)
Text: "Hi, I'm Sarah Chen from Anthropic. Reach me at sarah@anthropic.com"
"""}
]
)
try:
data = json.loads(response.content[0].text)
print(data)
except json.JSONDecodeError as e:
print(f"Parse failed: {e}")
print(f"Raw response: {response.content[0].text}")
Reliability comparison: In testing across 1,000 calls, tool use produced valid parseable JSON 99.7% of the time vs. 94.2% for system-prompt-only JSON instruction. For production pipelines processing thousands of records, that 5.5% gap matters significantly.
Nested and Complex Schemas
Tool use handles nested structures well:
product_tool = {
"name": "extract_product",
"description": "Extract product information",
"input_schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"currency": {"type": "string"}
},
"required": ["amount", "currency"]
},
"specifications": {
"type": "object",
"additionalProperties": {"type": "string"},
"description": "Key-value pairs of product specs"
},
"in_stock": {"type": "boolean"}
},
"required": ["name", "price", "in_stock"]
}
}
Production JSON extraction patterns
Agent SDK Cookbook ($49) includes 8 recipes for structured output extraction: batch document processing, schema validation pipelines, multi-model routing for structured data, and error recovery patterns.
Batch Structured Extraction
For processing multiple items:
def extract_structured(text: str, schema_tool: dict) -> dict:
"""Extract structured data using tool use."""
response = client.messages.create(
model="claude-haiku-4-5", # Use Haiku for cost efficiency on bulk extraction
max_tokens=1024,
tools=[schema_tool],
tool_choice={"type": "tool", "name": schema_tool["name"]},
messages=[{"role": "user", "content": text}]
)
tool_block = next((b for b in response.content if b.type == "tool_use"), None)
if tool_block is None:
raise ValueError("Claude did not call the expected tool")
return tool_block.input
# Process a batch
documents = ["doc1 text...", "doc2 text...", "doc3 text..."]
results = [extract_structured(doc, output_tool) for doc in documents]
Cost tip: Use claude-haiku-4-5 for structured extraction tasks. It handles well-defined schemas as reliably as Sonnet at 10x lower cost.
Schema Validation with Pydantic
Combine Claude's output with Pydantic for runtime validation:
from pydantic import BaseModel, ValidationError
from typing import Optional, List
class ArticleData(BaseModel):
title: str
summary: str
topics: List[str]
sentiment: str
word_count: Optional[int] = None
def extract_and_validate(text: str) -> ArticleData:
raw = extract_structured(text, output_tool)
try:
return ArticleData(**raw)
except ValidationError as e:
raise ValueError(f"Claude returned invalid structure: {e}")
article = extract_and_validate(article_text)
print(article.sentiment) # "positive"
print(article.topics) # ["benchmarks", "coding", ...]
This pattern gives you:
- Claude's language understanding for extraction
- Pydantic's type safety for downstream use
- Clear error messages when extraction fails
Handling Optional Fields
# Use Optional and default values in your schema
schema = {
"type": "object",
"properties": {
"required_field": {"type": "string"},
"optional_field": {
"type": ["string", "null"],
"description": "May not be present in all documents"
}
},
"required": ["required_field"]
# optional_field not in required list
}
Streaming Structured Output
For long structured responses, streaming isn't directly supported with tool use. Use a two-step approach: stream for long text generation, then extract structure:
# Step 1: Generate with streaming
with client.messages.stream(
model="claude-sonnet-4-5",
max_tokens=4096,
messages=[{"role": "user", "content": "Write a detailed product analysis..."}]
) as stream:
full_text = stream.get_final_text()
# Step 2: Extract structure from generated text
structured = extract_structured(f"Extract data from: {full_text}", output_tool)
Error Recovery Pattern
def robust_extract(text: str, tool: dict, max_retries: int = 2) -> dict:
for attempt in range(max_retries + 1):
try:
return extract_structured(text, tool)
except ValueError as e:
if attempt == max_retries:
raise
# On failure, add explicit instruction
text = f"""
IMPORTANT: You must call the {tool['name']} tool with valid inputs.
Extract this text: {text}
"""
return {}
Integration with Claude Code
For automated extraction pipelines run from Claude Code, see Claude Agent SDK Guide for multi-step extraction workflows. For cost optimization when running bulk extractions, see Claude API Cost and Prompt Caching Break-Even.
Frequently Asked Questions
What's the difference between tool use and JSON mode for structured outputs?
Tool use defines an explicit schema and forces Claude to return data matching that schema — it's more reliable. "JSON mode" (instructing Claude via system prompt to return JSON) is simpler but Claude may include text around the JSON or vary field names. Use tool use for production pipelines.
Can I use structured outputs with Claude Haiku?
Yes. Haiku supports tool use and produces reliable structured outputs for well-defined schemas. It's the recommended model for bulk extraction tasks due to its 10x cost advantage over Sonnet with comparable accuracy on structured tasks.
How do I handle arrays of objects in the output schema?
Define an array type with items pointing to an object schema: {"type": "array", "items": {"type": "object", "properties": {...}}}. Claude handles arrays of arbitrary length well.
What happens if Claude can't extract a required field?
Claude will either attempt to infer the value or return an empty string. To handle this: either make the field optional in your schema, or include a "confidence" field where Claude can signal uncertainty. For critical fields, validate the output and retry with a more explicit prompt.
Is there a limit on schema complexity?
No explicit limit, but very complex schemas (50+ fields, deeply nested) can reduce extraction accuracy. For complex documents, consider splitting into multiple targeted extraction calls rather than one large schema.
How do I extract from PDFs or images?
Pass the document as a base64-encoded image or PDF in the messages array alongside your tool definition. Claude's vision capabilities work with tool use — you can extract structured data from visual documents.
Complete structured output cookbook
Agent SDK Cookbook ($49) covers document pipelines, multi-schema routing, parallel extraction, and production error handling.