Getting Structured (JSON) Output

Two dependable ways to make Claude's output conform to a JSON shape you specify — and why you should still validate the result before your code trusts it.

Why "just ask for JSON" isn't reliable enough

☺ Like you're 10: Asking nicely for "JSON please" is like asking a friend to text you "the important stuff" — everyone's important stuff looks a little different. A form with labeled blanks is the only way to get the same shape back every time.

The obvious first attempt at structured output is to describe the shape you want in plain English and hope: "extract the name and email from this text and return it as JSON." That works often enough to feel safe in a demo, which is exactly what makes it dangerous in production. Nothing about a plain-English request constrains the model's output at the token level, so the same prompt can drift across runs — a friendly sentence before the JSON, the whole thing wrapped in a markdown code fence, a key renamed from email to email_address, or a number returned as the string "2" instead of the integer 2.

// Same prompt, two separate runs, no schema enforcement:

// Run 1
Here's the extracted contact info:
```json
{"Name": "Priya Nair", "Email": "priya.nair@fenwickrobotics.com"}
```

// Run 2
{
  "name": "Priya Nair",
  "email_address": "priya.nair@fenwickrobotics.com",
  "company": "Fenwick Robotics"
}

Every one of those variations breaks a naive json.loads() call, or silently produces the wrong field names downstream. The fix isn't a more carefully worded prompt — it's giving Claude a machine-checkable contract to fill in, rather than a description to interpret.

Approach 1: force the shape with an extraction tool

☺ Like you're 10: A forced tool call is a fill-in-the-blanks worksheet Claude has to hand in — it can't turn in a five-paragraph essay instead.

This is the standard "function-calling-as-extraction" pattern: you define a tool that's never actually executed — it exists purely so its input_schema becomes the contract Claude's output must satisfy. Combine it with strict: true and a forced tool_choice, and Claude's response is produced through grammar-constrained sampling against your schema instead of free-form text generation. As Anthropic's own docs put it: without strict mode, Claude might hand back the wrong type — a string where you asked for a number — or skip a required field entirely. Strict mode is what closes that gap.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

extract_contact_tool = {
    "name": "extract_contact",
    "description": (
        "Extract a single contact record from unstructured text. Use this "
        "whenever the input contains a person's name and email, optionally "
        "their company and role, and the caller wants that information "
        "returned as structured data rather than prose."
    ),
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "The person's full name"},
            "email": {"type": "string", "format": "email", "description": "The person's email address"},
            "company": {"type": "string", "description": "The company the person works for, if mentioned"},
            "role": {"type": "string", "description": "The person's job title or role, if mentioned"},
            "confidence": {
                "type": "number",
                "description": "How confident the extraction is, from 0.0 (guessing) to 1.0 (explicit in the text)"
            }
        },
        "required": ["name", "email", "confidence"],
        "additionalProperties": False
    }
}

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1000,
    tools=[extract_contact_tool],
    tool_choice={"type": "tool", "name": "extract_contact"},
    messages=[
        {
            "role": "user",
            "content": (
                "Reach out to Priya Nair, she's the VP of Engineering at "
                "Fenwick Robotics. Her email is priya.nair@fenwickrobotics.com."
            ),
        }
    ],
)

tool_use_block = next(block for block in message.content if block.type == "tool_use")
contact = tool_use_block.input
print(contact)
# {'name': 'Priya Nair', 'email': 'priya.nair@fenwickrobotics.com',
#  'company': 'Fenwick Robotics', 'role': 'VP of Engineering', 'confidence': 0.95}

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env

const extractContactTool = {
  name: "extract_contact",
  description:
    "Extract a single contact record from unstructured text. Use this " +
    "whenever the input contains a person's name and email, optionally " +
    "their company and role, and the caller wants that information " +
    "returned as structured data rather than prose.",
  strict: true,
  input_schema: {
    type: "object",
    properties: {
      name: { type: "string", description: "The person's full name" },
      email: { type: "string", format: "email", description: "The person's email address" },
      company: { type: "string", description: "The company the person works for, if mentioned" },
      role: { type: "string", description: "The person's job title or role, if mentioned" },
      confidence: {
        type: "number",
        description: "How confident the extraction is, from 0.0 (guessing) to 1.0 (explicit in the text)"
      }
    },
    required: ["name", "email", "confidence"],
    additionalProperties: false
  }
};

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1000,
  tools: [extractContactTool],
  tool_choice: { type: "tool", name: "extract_contact" },
  messages: [
    {
      role: "user",
      content:
        "Reach out to Priya Nair, she's the VP of Engineering at " +
        "Fenwick Robotics. Her email is priya.nair@fenwickrobotics.com."
    }
  ]
});

const toolUseBlock = message.content.find((block) => block.type === "tool_use");
const contact = toolUseBlock.input;
console.log(contact);

Note the shape of the request: tool_choice: {"type": "tool", "name": "extract_contact"} forces Claude to call exactly that tool, rather than deciding on its own whether to (the {"type": "auto"} default) or picking from several ({"type": "any"}). Because tool_choice forces a tool call, the API also skips any natural-language preamble internally — you get the tool_use block and nothing else.

Approach 2: prefilling, and its modern replacement

The older trick for nudging Claude toward JSON was response prefilling: instead of forcing a tool call, you supply the start of the assistant's reply yourself — typically an opening { — as the last message in the array, with role: "assistant". Claude's completion then continues directly from that text, which both skips any "Here is the JSON you asked for:" preamble and biases the token-by-token generation toward continuing valid JSON.

# Legacy pattern — only works on earlier model generations
# (e.g. claude-sonnet-4-5); returns a 400 error on Claude 4.6+ / Mythos.
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    messages=[
        {
            "role": "user",
            "content": (
                "Return the contact info below as JSON with keys name, "
                "email, company, role.\n\nPriya Nair, VP of Engineering "
                "at Fenwick Robotics, priya.nair@fenwickrobotics.com"
            ),
        },
        {"role": "assistant", "content": "{"},  # biases the continuation toward JSON
    ],
)

The official migration path for this exact use case — forcing an output format like JSON — is the Structured Outputs feature: set output_config.format to type: "json_schema" with your schema, and the entire message response is constrained to valid JSON matching it, no tool call involved.

contact_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "company": {"type": "string"},
        "role": {"type": "string"},
        "confidence": {"type": "number"}
    },
    "required": ["name", "email", "confidence"],
    "additionalProperties": False
}

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1000,
    output_config={"format": {"type": "json_schema", "schema": contact_schema}},
    messages=[
        {
            "role": "user",
            "content": (
                "Reach out to Priya Nair, she's the VP of Engineering at "
                "Fenwick Robotics. Her email is priya.nair@fenwickrobotics.com."
            ),
        }
    ],
)

text_block = next(block for block in message.content if block.type == "text")
contact = json.loads(text_block.text)  # guaranteed to match contact_schema

This shape isn't SDK-specific — the same output_config.format field works identically if you call the API directly over HTTP instead of through the Python or TypeScript SDKs. Both SDKs also expose a client.messages.parse() helper that takes a Pydantic model (Python) or Zod schema (TypeScript) directly and hands back a validated, typed object instead of a raw string you have to json.loads() yourself — worth reaching for once you're already defining schemas in application code.

Validate, then retry on failure

☺ Like you're 10: The form guarantees every blank is filled in with the right kind of answer — not that the answer makes sense. A permission slip can require a signature without checking whether you signed your own name or your dog's.

Strict tool schemas and json_schema output both guarantee type-correct, schema-shaped output — but the JSON Schema subset Claude supports is deliberately limited. It supports basic types, enum, const, anyOf/allOf, $ref/$def, and string formats like email or date-time. It does not support numeric constraints (minimum/maximum/multipleOf), string length constraints (minLength/maxLength), most array constraints, or recursive schemas. That confidence field from the extraction tool is guaranteed to be a number — but nothing stops Claude from returning 7.4 when your application only makes sense for values between 0.0 and 1.0. Business-rule validation still belongs in your code.

When validation fails, feed the failure back to Claude as a tool_result with is_error: true and a description of what to fix, then let it try again — the same mechanism used for ordinary tool execution errors.

def validate_contact(contact: dict) -> None:
    if not (0.0 <= contact["confidence"] <= 1.0):
        raise ValueError("confidence must be between 0.0 and 1.0")

def extract_contact(text: str, max_attempts: int = 3) -> dict:
    messages = [{"role": "user", "content": text}]

    for attempt in range(max_attempts):
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1000,
            tools=[extract_contact_tool],
            tool_choice={"type": "tool", "name": "extract_contact"},
            messages=messages,
        )
        tool_use_block = next(b for b in message.content if b.type == "tool_use")
        contact = tool_use_block.input

        try:
            validate_contact(contact)
            return contact
        except ValueError as e:
            # tool_result must immediately follow the tool_use turn, and
            # come before any text in that user message's content array.
            messages.append({"role": "assistant", "content": message.content})
            messages.append({
                "role": "user",
                "content": [{
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Invalid output: {e}. Call extract_contact again with a corrected value.",
                    "is_error": True,
                }],
            })

    raise RuntimeError(f"Could not extract a valid contact after {max_attempts} attempts")

Choosing an approach

Three techniques, three different trade-offs. Here's how they stack up side by side.

In practice: reach for the extraction tool when structured output is one call inside a larger agentic loop that already uses tools, and reach for output_config.format when extraction is the entire point of the request and there's no reason to route it through a tool call at all. Skip prefilling for new work — it's a legacy pattern that current models don't accept.