How Do You Get Reliable JSON From Claude?
On the API, set output_config.format with a JSON schema for the response, or strict: true on a tool for its inputs. Anthropic says these use constrained decoding, so the output always parses and matches your schema, apart from a few documented exceptions. Valid JSON can still contain wrong facts, so you still need to check the values.
Request settings:
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"category": { "type": "string", "enum": ["[option 1]", "[option 2]", "needs_review"] },
"evidence": { "type": "string", "description": "Exact quote from the input" },
"explanation": { "type": "string", "description": "One short sentence" }
},
"required": ["category", "evidence", "explanation"],
"additionalProperties": false
}
}
}
Prompt:
Classify this input. Use "needs_review" if none clearly fit, and don't guess.
<input>[text]</input>
- prefilling the response with {
- forced tool_choice on current models
- output_config.format for answers
- strict: true for tool inputs
- 20strict tools per request
- 24optional parameters
- 16parameters with union types
Try it now
- 1Take a request in your code that asks for JSON in the prompt, and add the
output_configblock above with your own fields. - 2Remove any prefill, along with any regex that cleans up the response.
- 3In your code, check
stop_reasonbefore parsing, then run 20 real inputs. - 4You'll know it worked if every response parses with no cleanup. Then compare the
evidencevalues with the inputs. That's the part the schema can't check.
Use it when
Skip it when
Skip it when a person reads the result, since prose is better there. It's also the wrong fit for recursive data, or anything needing minimum, maximum, minLength or maxLength enforced by the schema. Those return a 400, so validate them in your code instead.
Why it works
Anthropic's docs say structured outputs mean no JSON.parse() errors and no retries for schema violations, on Haiku 5.5, Sonnet 5.5, Opus 5.5, Fable 5.1 and other supported models. The older tricks are going away. Prefilled responses return a 400 starting with the Claude 4.6 models, and forced tool_choice of any or tool returns a 400 on Opus 5.5, Sonnet 5.5 and Fable 5.1. On models that do accept it, forcing a tool also skips thinking. The SDK's client.messages.parse() takes a Pydantic or Zod schema and returns a parsed result.
Example
You sort incoming invoices into approve, query and needs_review, and code routes each one. The schema makes category one of those values, and makes evidence required, holding the line it relied on. Your code then checks that the amount in evidence really appears in the invoice, which catches a well-formed answer that's wrong.
Going further
Three exceptions still reach your code. stop_reason: "refusal" returns a 200, is billed and may not match the schema. "max_tokens" can leave output incomplete. And enums can change capitalization, so compare them case-insensitively. Limits are 20 strict tools per request, 24 optional parameters and 16 parameters with union types, across all your schemas, and too large a schema returns "Schema is too complex for compilation." New schemas add compile latency, and compiled grammars are cached for 24 hours from last use. Changing only a name or description doesn't invalidate that cache.
Common mistakes
- Upgrading a model and keeping a prefill or forced
tool_choice, which turns working code into 400 errors. - Treating a schema match as proof the content is right. It guarantees the shape, not the facts.
- Parsing without checking
stop_reason, so a refusal or a truncated response slips into your data. - Adding a
reasoningfield to the schema. Anthropic says that can trigger areasoning_extractionrefusal. Useexplanationorevidence.
Sources
- Structured outputs, Claude Platform Docs
- Define tools, Claude Platform Docs
- Prompting best practices, Claude Platform Docs
- Refusals and fallback, Claude Platform Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.