Structured Outputs with Claude: Getting JSON Every Time

Every real production application that uses an AI model faces the same fundamental challenge: the AI speaks in natural language, but your code needs structured data. You need a list, not a paragraph. You need a JSON object with specific fields, not a conversational reply. You need machine-readable output that you can parse, validate, and store reliably.

Claude is highly capable of producing structured output, but it requires intentional design. Left to its defaults, Claude will produce well-written prose. This guide covers every technique available for extracting structured, schema-compliant JSON from Claude — from simple prompt engineering to using the tool-use API as a structured output mechanism.

Why Structured Output Matters in Production

Consider a typical AI-powered feature: a resume parser that extracts candidate data from uploaded CVs. You might want Claude to extract the candidate's name, email, work history, and skills. If Claude returns a friendly paragraph summarising the candidate, your application cannot process it. You need a JSON object.

The same challenge applies to:

Classification systems that must return one of a fixed set of labels
Sentiment analysis pipelines that feed scores to analytics databases
Data extraction workflows that populate CRM fields from unstructured text
API orchestration layers that route based on Claude's decision output

Getting structured output right is not optional — it is the difference between a demo and a production system.

Technique 1 — Prompt Constraints (Simplest Approach)

The simplest approach is to instruct Claude explicitly in your system prompt to return only JSON and nothing else.

python

import anthropic
import json

client = anthropic.Anthropic()

system_prompt = """You are a data extraction assistant.
You MUST respond ONLY with valid JSON. Do not include any explanation, 
preamble, or markdown code fences. Return raw JSON only.
The JSON must match this schema exactly:
\{
  "sentiment": "positive" | "negative" | "neutral",
  "confidence": 0.0 to 1.0,
  "key_topics": ["string", "string"]
}"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=system_prompt,
    messages=[{
        "role": "user",
        "content": "Analyse this review: 'The product arrived quickly but the quality was disappointing for the price.'"
    }]
)

output = json.loads(response.content[0].text)
print(output)
# {"sentiment": "negative", "confidence": 0.82, "key_topics": ["delivery", "quality", "price"]}

This works well for simple schemas and in development. However, for complex schemas or in high-volume production, you should use the tool-use approach below for stronger reliability guarantees.

Never Blindly Parse AI Output

Always wrap json.loads() in a try/except block. Even with strict instructions, edge cases can produce invalid JSON — particularly for complex documents or unusual inputs. Implement a validation step after parsing to confirm the data matches your expected schema before using it in downstream systems.

Technique 2 — Assistant Prefill

Assistant prefill is a powerful technique where you begin Claude's response for it. By starting the response with an opening brace, you force Claude to complete a JSON object.

python

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="Extract the requested data as JSON only.",
    messages=[
        {
            "role": "user",
            "content": "Extract name, role, and company from: 'Hi, I'm Sarah Chen, a Senior DevOps Engineer at Meridian Systems.'"
        },
        {
            "role": "assistant",
            "content": "\{"  # Claude must continue from here
        }
    ]
)

# Claude's response continues from the \{ we provided
raw_json = "\{" + response.content[0].text
output = json.loads(raw_json)
# {"name": "Sarah Chen", "role": "Senior DevOps Engineer", "company": "Meridian Systems"}

This technique works because Claude cannot insert explanatory text before the JSON — the opening brace has already been placed. It is reliable for straightforward extraction tasks.

Technique 3 — Tool Use for Structured Output (Production-Grade)

The most reliable technique for getting structured output from Claude is using the tool-use API in an unconventional but highly effective way: you define a tool with your desired output schema, and Claude is forced to call that tool with valid arguments matching your schema.

This works because Claude's tool-calling mechanism inherently produces structured, schema-validated output. Claude cannot return free-form text when it is in the process of calling a tool.

python

import anthropic
import json

client = anthropic.Anthropic()

# Define your desired output shape as a tool
extract_candidate_tool = {
    "name": "extract_candidate_data",
    "description": "Extract structured candidate information from a CV or resume text",
    "input_schema": {
        "type": "object",
        "properties": {
            "full_name": {
                "type": "string",
                "description": "The candidate's full name"
            },
            "email": {
                "type": "string",
                "description": "Email address"
            },
            "years_experience": {
                "type": "number",
                "description": "Total years of professional experience"
            },
            "skills": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of technical skills mentioned"
            },
            "current_role": {
                "type": "string",
                "description": "Most recent job title"
            }
        },
        "required": ["full_name", "email", "skills"]
    }
}

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[extract_candidate_tool],
    tool_choice={"type": "any"},  # Force Claude to use a tool
    messages=[{
        "role": "user",
        "content": cv_text  # Your resume text here
    }]
)

# Extract the structured data from the tool call
for block in response.content:
    if block.type == "tool_use":
        candidate_data = block.input
        print(candidate_data)

The tool_choice: {"type": "any"} parameter is critical — it forces Claude to call one of the provided tools rather than responding in plain text.

Tool Use for Output, Not Just Actions

Most developers think of tool use as a mechanism for giving Claude the ability to call external APIs — web search, calculators, databases. But tool use is equally valuable as a structured output mechanism. The input_schema in your tool definition acts as a JSON Schema validator, and Claude is constrained to produce valid arguments matching that schema. This is the most reliable path to structured output in production.

Technique 4 — Chain of Thought Before JSON

For complex extraction tasks where raw JSON instructions cause Claude to miss nuance, you can use a two-step approach: first ask Claude to think through the problem in prose, then extract the final answer as JSON.

python

# Step 1: Analysis pass
analysis_response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": f"Analyse this contract for key obligations, parties, and risk factors:\n\n{contract_text}"
    }]
)

analysis = analysis_response.content[0].text

# Step 2: Structured extraction
extraction_response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[contract_extraction_tool],
    tool_choice={"type": "any"},
    messages=[
        {"role": "user", "content": f"Contract: {contract_text}"},
        {"role": "assistant", "content": analysis},
        {"role": "user", "content": "Now extract the key data into the structured format."}
    ]
)

This approach gives Claude the reasoning space to understand the content deeply before committing it to a rigid schema.

Defining Robust JSON Schemas

The quality of your output depends heavily on your schema definition. A vague schema produces inconsistent output.

Good Schema Practices

Be specific about types: Use "type": "string", "type": "number", "type": "boolean", "type": "array" explicitly
Add clear descriptions: Each field's "description" property should explain exactly what data belongs there — Claude reads these when filling values
Use enums for fixed values: "enum": ["low", "medium", "high"] constrains the output to valid options
Mark required fields: The "required" array ensures Claude always populates your critical fields even when the data is not present in the source
Handle missing data: Define a null-able or optional field for data that may not be in the source rather than allowing Claude to invent values

Validation After Extraction

Never trust raw output — validate it against your schema before use.

python

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
        "confidence": {"type": "number", "minimum": 0.0, "maximum": 1.0}
    },
    "required": ["sentiment", "confidence"]
}

try:
    validate(instance=output, schema=schema)
    # Output is valid — proceed
except ValidationError as e:
    # Log the error and handle gracefully
    print(f"Validation failed: {e.message}")

Log Invalid Outputs for Prompt Refinement

When validation fails in production, log the raw output alongside the input that triggered it. These failure cases are gold for improving your schema definitions and system prompt. A pattern of failures on a particular field type or input category tells you exactly where your prompt or schema needs strengthening.

Summary

Getting reliable structured output from Claude is one of the most critical skills in building production AI applications. The four techniques in this guide — from simple to most reliable:

Prompt constraints: Simplest, fine for development and low-volume tasks
Assistant prefill: Reliable for straightforward extraction with known structure
Tool use as output mechanism: Most reliable, production-grade, schema-enforced
Chain of thought then extract: Best for complex documents requiring understanding before extraction

In the next post, we pause before diving into advanced features to consolidate everything covered so far on prompt engineering. It is a rapid-fire refresher of the ten techniques every Claude developer should have at their fingertips: Prompt Engineering Refresher: 10 Techniques Every Developer Should Know.

This post is part of the Anthropic AI Tutorial Series. Previous post: Claude Extended Thinking: How to Unlock Deep Reasoning.