Structured Output Extraction

Structured Output Extraction

Claude can be guided to return reliably structured output using tool_use, Pydantic schemas, or explicit JSON formatting.

Pattern 1: tool_use for structured output (most reliable)

from anthropic import Anthropic
import json

client = Anthropic()

# Define the schema as a tool
tools = [{
    "name": "extract_data",
    "description": "Extract structured data from text",
    "input_schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
            "score": {"type": "number", "minimum": 0, "maximum": 10},
            "keywords": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["name", "sentiment", "score"]
    }
}]

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "extract_data"},
    messages=[{"role": "user", "content": "Analyze: Great product, love it! Score: 9/10"}]
)

result = json.loads(response.content[0].input)
# result = {"name": "product", "sentiment": "positive", "score": 9, "keywords": ["great", "love"]}

Pattern 2: instructor library

import anthropic
import instructor
from pydantic import BaseModel

client = instructor.from_anthropic(anthropic.Anthropic())

class SentimentAnalysis(BaseModel):
    sentiment: str
    score: float
    reasoning: str

result = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Analyze sentiment: Best product ever!"}],
    response_model=SentimentAnalysis
)
# result.sentiment, result.score, result.reasoning are all typed

Pattern 3: Pydantic-AI agent

from pydantic_ai import Agent
from pydantic import BaseModel

class ExtractedData(BaseModel):
    title: str
    summary: str
    tags: list[str]

agent = Agent("anthropic:claude-sonnet-4-6", result_type=ExtractedData)
result = agent.run_sync("Extract from: ...")
print(result.data.title)  # typed, validated

When to use each pattern

• tool_use → No extra dependencies, most reliable, works with any SDK
• instructor → Complex schemas, automatic retry on validation failure, Pydantic ecosystem
• pydantic-ai → Full agent systems needing typed state management

Common pitfalls

• Don't use plain JSON prompting for critical parsing — models hallucinate formatting
• Always validate output even with tool_use (numbers can come as strings)
• For nested schemas, prefer tool_use over prompt-based JSON

Related skills

api-contracts-and-zod-validation, claude-api-integration

Related Skills

• instructor — structured extraction library
• zod-expert — validation schemas
• dspy — pipeline optimization

GitNexus Index

This skill is indexed by GitNexus for knowledge graph traversal. Index path: /Users/localuser/.claude/skills/structured-output-extraction/.gitnexus Last indexed: 2026-05-23