Claude API structured outputs — guarantee output with a JSON schema

Even when you prompt "answer only in JSON," the model can wrap output in markdown or add commentary that breaks parsing. Structured outputs constrain the response to a defined schema, guaranteeing directly parseable output. This guide covers the two modes, how it works, and pitfalls, grounded in the official docs. (Official: platform.claude.com/docs · as of September 2026, re-checked against the structured-outputs docs)

Why you need it

Forcing JSON with prompt engineering alone leaves problems:

• responses wrapped in markdown code blocks or padded with chatter
• regex parsing breaks the moment the format shifts
• schema violations require error handling and retries

Structured outputs turn this from a "request" into a "guarantee." The official docs recommend this feature over prompt techniques when you always need valid JSON.

Two modes

• JSON output (output_config.format) — get the whole response in a specified JSON shape. Good for data extraction and structured replies.
• Strict tool use (strict: true) — guarantee that tool names and inputs follow the schema. Good for complex tools and agentic workflows.

You can use them independently or together in one request.

How it is guaranteed

Structured outputs compile your JSON schema into a grammar, then constrain generation so no token can violate those rules (constrained decoding). The model simply cannot produce schema-violating output. More complex schemas take longer to compile, so very large schemas should be simplified.

How to use it

Define the data shape you want as a JSON schema and pass it in.

# Define the desired output shape as a schema
schema = {
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "price": {"type": "number"},
    "in_stock": {"type": "boolean"}
  },
  "required": ["name", "price"]
}
# Pass this schema via output_config.format (official docs, September 2026; no beta header needed).
# msg = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
#     output_config={"format": {"type": "json_schema", "schema": schema}},
#     messages=[...])
# The old beta output_format field and beta header are accepted only for a transition period;
# the Python SDK (1.0+) raises a TypeError if you pass output_format to the beta create().

SDKs make it easier: define schemas with Pydantic (Python) or Zod (TypeScript), and the SDK auto-simplifies unsupported constraints (min/max, etc.), reflecting them in descriptions (your code still enforces them).

Things to watch

• Availability/status — as of September 2026 the feature is generally available and beta headers are no longer required. Supported models include Opus 5, Sonnet 5, Fable 5.1, Opus 4.6–4.8, Sonnet 4.6, Sonnet 4.5, Opus 4.5, and Haiku 4.5 (Bedrock: the 4.5/4.6 families only). The parameter moved from output_format to output_config.format, so don't reuse old samples verbatim (only the messages.parse() helper still accepts output_format= for convenience). Supported models can change, so the official docs are the source of truth.
• Incompatibilities — Citations and message prefilling can't be combined (using citations with it returns a 400).
• Trade-off with extended thinking — if reasoning matters more, extended thinking may fit better. Grammar constraints don't apply to the thinking region.
• Simplify schemas — break overly complex schemas into smaller, simpler ones.

Related guides

For how tool use works, see the Tool Use guide; for the first call, see getting started; for errors/limits, see handling errors and rate limits.

Structured-outputs parameters, beta headers, supported models, and GA status may change; verify the latest in the official docs (platform.claude.com/docs). This site is not an official Anthropic site.

To receive tables, lists, or JSON in chat without writing code, see specifying Claude's output format.

See also: Tool use best practices

Related articles

• Claude API Tool Use Guide: How Function Calling Works
• Claude API Tool Use Best Practices: Definitions, Errors, Parallel Calls
• Getting Started with the Claude API: Your First Call (Developer Intro)
• Claude API Keys: Getting a Key, Pricing & Usage (2026)
• Getting Started with the Claude SDK (Python & TypeScript)