Structured Outputs

Structured outputs make the Claude API return valid JSON that matches a schema you supply: add output_config.format with "type": "json_schema" and a JSON Schema, and Claude's reply is constrained, token by token, to fit it (Structured outputs). The same mechanism, applied to tool arguments, is strict tool use ("strict": true on a tool). Claude has no separate "JSON mode" switch; this is the feature that does that job, and it goes further, since the output must match your exact fields and types rather than merely parse. It works on every current model, launched in beta on Nov 14, 2025 and became generally available on Jan 29, 2026.

Quick facts

Sources: Structured outputs and Citations, Anthropic docs, read Nov 6, 2026.

How do you get JSON from Claude?

Put the schema in output_config.format. Anthropic's example pulls contact details out of an email:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."}],
    "output_config": {
      "format": {
        "type": "json_schema",
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "email": {"type": "string"},
            "plan_interest": {"type": "string"},
            "demo_requested": {"type": "boolean"}
          },
          "required": ["name", "email", "plan_interest", "demo_requested"],
          "additionalProperties": false
        }
      }
    }
  }'

The answer arrives as a text block containing JSON with those four fields. Required properties are written first, then optional ones, whatever order the schema lists them in.

The SDK helpers

The SDKs turn a native type into a schema and parse the reply back into it. In Python, with Pydantic:

from pydantic import BaseModel

class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Extract the key information from this email: ..."}],
    output_format=ContactInfo,
)
print(response.parsed_output)

TypeScript uses Zod schemas through zodOutputFormat(), and the Java, PHP and Ruby SDKs accept classes; each returns the typed result in parsed_output (Structured outputs). In the Python SDK from version 1.0, passing output_format to a plain create() call raises a TypeError: use parse(), or output_config with a raw schema.

Strict tool use

When Claude calls your functions instead of answering in JSON, add "strict": true to the tool definition and its input will always match the tool's input_schema (Strict tool use). Without it, Claude can occasionally send a string where an integer belongs or skip a required field. Strict tools matter more on the newest models: Opus 5.5, Sonnet 5.5 and Fable 5.1 reject forced tool use (tool_choice any or tool), and Anthropic's suggested replacement is auto plus strict tools (Release notes). The loop itself is on Tool Use.

Which JSON Schema features are supported?

Most of standard JSON Schema works: objects, arrays, strings, numbers, booleans, enums, required, anyOf and $ref within the schema. These return a 400 error (Structured outputs):

• Recursive schemas, and external $ref.
• Numeric limits (minimum, maximum, multipleOf) and string length limits (minLength, maxLength).
• Array limits other than minItems of 0 or 1.
• additionalProperties set to anything but false.
• Regex patterns with backreferences, lookaround or word boundaries.

Across all strict schemas in one request the totals are capped at 20 strict tools, 24 optional parameters and 16 parameters with union types. A schema too large to compile returns "Schema is too complex for compilation", and compilation gives up after 180 seconds. A common workaround for an unsupported limit is to describe it in the field's description and check it in your code after parsing.

When the output can still be wrong

The schema guarantees shape, not truth: Claude can fill a valid field with a wrong value, so check facts that matter. Two cases also break the shape. If the reply hits max_tokens (stop_reason: "max_tokens"), the JSON is cut off; raise the limit and retry. If Claude refuses (stop_reason: "refusal"), the reply may not match the schema at all. Always read stop_reason before parsing (Messages API).

Limits and compatibility

• The first request with a new schema is slower while the grammar compiles; after that the grammar is cached for 24 hours from last use. Changing the schema means a new compile.
• Structured outputs and citations cannot be used together; the request returns an error (Citations).
• Prefilling a JSON opening brace, an older trick for getting JSON, returns a 400 error on Claude 4.6 and later models, which is part of why structured outputs replaced it (Using the Messages API).
• It works on every platform that sells Claude, including Amazon Bedrock and Google Cloud, and with the Message Batches API. Under zero data retention only the schema is cached, for up to 24 hours.

Frequently asked questions

Does Claude have a JSON mode? Claude has no switch named JSON mode; Claude's structured outputs (output_config.format with a JSON Schema) do the job and guarantee the reply matches your schema, not just that it is valid JSON.

Which Claude models support structured outputs? All current Claude models (Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5) and the older Opus 5, Sonnet 5, Opus 4.8 to 4.5, Sonnet 4.6 and 4.5, and Haiku 4.5 support structured outputs on the Claude API.

What is the difference between Claude structured outputs and strict tool use? Both constrain Claude with your JSON Schema. Structured outputs shape Claude's final answer; strict tool use (strict: true) shapes the arguments Claude passes when it calls one of your tools.

Why does Claude return a 400 error for my schema? The Claude API rejects schema features it cannot compile, such as minimum, maxLength, recursion or additionalProperties: true, and schemas past the limits of 20 strict tools, 24 optional parameters or 16 union-type parameters per request.

Can Claude's structured output still be invalid? Rarely: if Claude stops at max_tokens the JSON is truncated, and a refusal may not follow the schema. Check that stop_reason is end_turn before parsing.

Sources

• Structured outputs, Anthropic docs, read Nov 6, 2026
• Strict tool use, Anthropic docs, read Nov 6, 2026
• Citations, Anthropic docs, read Nov 6, 2026
• Using the Messages API, Anthropic docs, read Nov 6, 2026
• Release notes, Anthropic docs, read Nov 6, 2026