Claude Structured Output: JSON Mode, Tool Use & Reliable Data Extraction

Getting Claude to write a compelling analysis is easy. Getting Claude to return a specific JSON schema reliably enough to build a production system on top of it — that requires deliberate engineering. Claude structured output is the discipline of designing your API integration so that Claude's responses fit predictable data structures that your downstream code can parse, validate, and act on without brittle string manipulation or fragile JSON extraction.

This guide covers every technique for getting reliable structured output from Claude: prompt engineering approaches for JSON compliance, the tool use API for schema-enforced extraction, response validation and error recovery, and the tradeoffs between different approaches for different use cases. For enterprise teams building data extraction pipelines, document processing workflows, or agentic systems that depend on typed inputs, this is the pattern reference you need.

Three Approaches to Structured Output

Claude doesn't have a dedicated "JSON mode" like some other APIs — instead, you achieve structured output through three increasingly reliable methods, each with different tradeoffs in flexibility, reliability, and cost.

Approach 1: Prompt Instructions for JSON

The simplest approach is instructing Claude in the system prompt to return JSON in a specified format. This works reliably for straightforward schemas with Claude Sonnet and Opus, but produces occasional failures — extra text before or after the JSON, markdown code fences, schema deviations under ambiguous inputs — that require defensive parsing.

import anthropic, json, re

client = anthropic.Anthropic()

SYSTEM_PROMPT = """You are a document analysis assistant.

IMPORTANT: You must ALWAYS respond with ONLY valid JSON matching this exact schema:
{
  "document_type": "string (invoice, contract, report, or other)",
  "key_entities": ["array of company/person names"],
  "dates": ["array of dates in YYYY-MM-DD format"],
  "monetary_values": ["array of currency amounts as strings"],
  "summary": "string, 2-3 sentence summary",
  "confidence": number between 0.0 and 1.0
}

Do NOT include any text outside the JSON object.
Do NOT use markdown code blocks.
Do NOT include trailing commas."""

def extract_document_data(document_text: str) -> dict:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=SYSTEM_PROMPT,
        messages=[{
            "role": "user",
            "content": f"Analyse this document:\n\n{document_text}"
        }]
    )

    raw = response.content[0].text.strip()

    # Defensive extraction: strip code fences if present
    if raw.startswith("```"):
        raw = re.sub(r'^```(?:json)?\n?', '', raw)
        raw = re.sub(r'\n?```$', '', raw)

    return json.loads(raw)

Approach 2: Assistant Prefill for JSON Responses

A more reliable technique is prefilling the assistant's response with the opening { of the JSON object. When you include an assistant turn in your messages array ending with {"{"}, Claude continues generating from that starting point, making it far less likely to insert preamble text before the JSON.

def extract_with_prefill(document_text: str) -> dict:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system="Extract document data as JSON. Return only the JSON object.",
        messages=[
            {
                "role": "user",
                "content": f"Extract from this document:\n\n{document_text}"
            },
            {
                "role": "assistant",
                "content": "{"  # Prefill forces Claude to complete the JSON
            }
        ]
    )

    # Response continues from the { we prefilled
    raw = "{" + response.content[0].text
    return json.loads(raw)

Prefilling is particularly effective for ensuring Claude doesn't add a preamble like "Here is the extracted data:" before the JSON. The cost is that you're slightly constraining Claude's ability to express uncertainty — it can't preface its response with qualifications. For production extraction pipelines that prioritise reliability over natural language explanations, this tradeoff is usually worth it.

Approach 3: Tool Use for Schema-Enforced Extraction

Tool use (also called function calling) is the most reliable approach for structured output. You define a tool with a JSON Schema describing your desired output structure, and Claude calls that tool with arguments matching the schema. The API enforces schema compliance at the infrastructure level — not just through prompt instructions.

import anthropic, json

client = anthropic.Anthropic()

# Define extraction tool with complete JSON Schema
EXTRACTION_TOOL = {
    "name": "extract_document_data",
    "description": "Extract structured data from the provided document",
    "input_schema": {
        "type": "object",
        "properties": {
            "document_type": {
                "type": "string",
                "enum": ["invoice", "contract", "purchase_order", "report", "other"],
                "description": "The type of business document"
            },
            "parties": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "role": {"type": "string", "enum": ["buyer", "seller", "counterparty", "issuer", "other"]},
                        "address": {"type": "string"}
                    },
                    "required": ["name", "role"]
                }
            },
            "effective_date": {
                "type": "string",
                "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
                "description": "Document date in YYYY-MM-DD format"
            },
            "total_value": {
                "type": "number",
                "description": "Total monetary value, in base currency units"
            },
            "currency": {
                "type": "string",
                "description": "ISO 4217 currency code (USD, EUR, GBP, etc.)"
            },
            "key_obligations": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of key obligations or line items"
            },
            "risk_flags": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Potential risks or clauses requiring review"
            },
            "extraction_confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
            }
        },
        "required": ["document_type", "parties", "extraction_confidence"]
    }
}

def extract_with_tool_use(document_text: str) -> dict:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        tools=[EXTRACTION_TOOL],
        tool_choice={"type": "tool", "name": "extract_document_data"},  # Force tool use
        messages=[{
            "role": "user",
            "content": f"Extract structured data from this document:\n\n{document_text}"
        }]
    )

    # Find the tool use block
    for block in response.content:
        if block.type == "tool_use" and block.name == "extract_document_data":
            return block.input  # Already parsed as dict — no JSON parsing needed

    raise ValueError("No tool use block in response")

The key advantage of tool use for Claude structured output is the tool_choice parameter. Setting it to {"type": "tool", "name": "extract_document_data"} forces Claude to call that specific tool rather than choosing whether to use tools. The input arrives as a parsed Python dict — not a JSON string — so there's no JSON parsing step and therefore no JSON parse errors. This approach is what we recommend for all production data extraction pipelines. For guidance on building complete extraction systems, see the Claude tool use guide.

Schema Design for Reliable Extraction

The quality of your JSON Schema directly determines the reliability of your structured output. Poorly designed schemas produce ambiguous field names that confuse Claude, missing enums where a constrained value set exists, and optional fields that should be required — all of which lead to extraction failures or missing data in production.

Write descriptions for every field in your schema. Claude uses these descriptions to understand what to extract, especially for fields where the name alone is ambiguous. "date" is ambiguous — "effective_date: the date the contract takes effect, in YYYY-MM-DD format" is not. Use enums wherever the valid value set is bounded — "type": "string", "enum": ["invoice", "contract", "po"] is far more reliable than a free-text string field where Claude has to guess the right vocabulary.

Mark fields as required only when they should always be present in valid documents. If a field is sometimes missing (e.g., contract expiration date on open-ended contracts), leave it optional and handle the null case in your downstream code. A schema that Claude can always fully populate is more reliable than one that occasionally requires Claude to invent values to satisfy required field constraints.

Response Validation and Error Recovery

Even with tool use enforcing schema compliance, validation at the application layer is essential. Schema compliance guarantees that required fields are present and types are correct — it doesn't guarantee that the values are semantically correct. A date field might be present but contain "N/A" instead of a date string. A confidence field might be 0.95 when the document was clearly illegible. Validate business logic in your application, not just schema structure.

from jsonschema import validate, ValidationError
from datetime import datetime

BUSINESS_RULES = {
    "effective_date_format": r"^\d{4}-\d{2}-\d{2}$",
    "confidence_minimum": 0.6,  # Flag low-confidence extractions for review
    "required_for_invoices": ["total_value", "currency"],
}

def validate_extraction(data: dict) -> tuple[bool, list[str]]:
    """Validate extracted data against business rules. Returns (valid, errors)."""
    errors = []

    # Validate date format if present
    if "effective_date" in data:
        try:
            datetime.strptime(data["effective_date"], "%Y-%m-%d")
        except ValueError:
            errors.append(f"Invalid date format: {data['effective_date']}")

    # Flag low-confidence extractions
    if data.get("extraction_confidence", 1.0) < BUSINESS_RULES["confidence_minimum"]:
        errors.append(f"Low confidence extraction: {data['extraction_confidence']:.2f}")

    # Invoice-specific validation
    if data.get("document_type") == "invoice":
        for field in BUSINESS_RULES["required_for_invoices"]:
            if field not in data:
                errors.append(f"Missing required invoice field: {field}")

    return len(errors) == 0, errors

def extract_and_validate(document_text: str) -> dict:
    """Extract and validate with retry on validation failure."""
    data = extract_with_tool_use(document_text)
    valid, errors = validate_extraction(data)

    if not valid:
        # Log for review queue rather than failing silently
        queue_for_human_review(data, errors)

    data["validation_errors"] = errors
    data["requires_review"] = not valid
    return data

Build a human review queue for extractions that fail validation or fall below confidence thresholds. Don't silently discard or auto-correct these — they represent either edge cases your prompts don't handle well (fix the prompt) or genuinely ambiguous documents (flag for human review). Track the rate at which documents enter the review queue; a rising rate signals prompt degradation or a shift in document types reaching your system.

Handling Complex and Nested Schemas

Claude handles deeply nested JSON schemas reliably when the schema is well-documented and the document content clearly maps to the expected structure. Where it struggles is when schemas have many optional nested objects and the document provides partial evidence for each. In these cases, break the extraction into multiple focused calls rather than one large schema — extract top-level data in the first call, then extract nested details from relevant sections in follow-up calls with more focused schemas.

For very long documents with a large number of extraction targets, use prompt caching to avoid paying full input token costs on each extraction pass. Cache the document text in the system prompt and vary only the extraction instruction in the user turn. This can reduce costs by 70-90% for multi-pass extraction workflows over long documents. For complex document classification systems, see how Claude RAG architectures handle multi-document retrieval and extraction at scale. Our full Claude API integration service includes document processing architecture design.

Related Articles