What you will be able to do
- Say what JSON outputs and strict tool use guarantee about a response, and what they leave unchecked
- Check stop_reason before parsing, and handle truncated or refused responses without trying to repair them
- Explain why the first request with a new schema is slower than later ones
- Use SDK validation, including constraints the API cannot enforce, to protect downstream code
- Pull JSON safely out of free-text responses when structured outputs are not in use
Key concept
Constrained decoding guarantees shape, not truth — Structured outputs limit which tokens Claude can sample, so a completed response is valid JSON with the declared types and required fields. It does not check whether the values are correct, and it does not prevent a response from being cut off or refused.
1.What a schema guarantees, and what it leaves to you
Downstream code breaks when model output arrives in the wrong shape. A billing job expects quantity as a number and gets the string "2". A router expects a priority key and finds that it is missing. A parser hits a stray sentence before the opening brace. Claude offers two ways to prevent these failures. JSON outputs put a JSON Schema in output_config.format with type: "json_schema", and Claude's text block comes back matching that schema. Strict tool use adds "strict": true to a tool definition, so the tool name is always valid and the input always matches its input_schema. You can use either one alone, or both in the same request.
Both features work by constraining which tokens the model is allowed to sample, not by asking it nicely. In a booking tool that declares passengers as an integer, a model without strict mode might send "two" or "2". With strict: true, the input is always 2. Grammar-constrained sampling removes three problems: JSON syntax errors, missing required fields, and wrong types. It also removes the validate-and-retry loop you would otherwise write for schema violations.
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)The guarantee covers form and nothing else. The grammar knows that priority must be one of the enum values and that summary must be a string. It cannot know which priority a ticket deserves, or whether the summary matches the ticket text. Nothing in decoding compares the output with your input document. A schema-valid response can still put an urgent outage in the low bucket. If correctness matters, check it with evaluations or business rules. Adding more schema will not catch it.
The guarantee also does not cover length. The grammar does not force the model to close every object before max_tokens, so a response that hits the limit can be incomplete and fail the schema.
Checkpoint 1 of 9· Fill the gap
This code reads a JSON outputs response (schema sent in output_config.format) from a raw messages.create call. Which block type holds the schema-matching JSON?
text = next(block.text for block in response.content if block.type == ? )
contact = json.loads(text)
print(contact)With JSON outputs, Claude puts the JSON that matches the schema in the response's text content block, so you can pass it straight to json.loads. The tool_use block's input is where strict tool use puts its guaranteed output, not JSON outputs.
Source: platform.claude.comCheckpoint 2 of 9· Check yourself
A ticket-triage request sends a JSON schema in output_config.format with type "json_schema". Most replies parse fine, but on one very long ticket json.loads fails on the text block because the closing braces are missing. What is the most likely cause?
The grammar guarantees syntax, required fields and types, but not length. A reply that reaches max_tokens can stop partway through the object, so check stop_reason and raise max_tokens.
“max_tokens | The response reached your max_tokens limit. | Raise max_tokens or continue the response.”Source: platform.claude.com
Checkpoint 3 of 9· Exam question
A support-ticket triage service requests JSON through the structured outputs feature with a schema listing priority as an enum and summary as a string. The team wants to know what downstream code can safely assume without extra checks. Which assumption is justified?
Correct answer: A — The response text parses as JSON and each required field is present with the declared type, so no JSON syntax repair step is needed.
- A. Correct: constrained decoding guarantees syntactically valid JSON with required fields and declared types, so repair of syntax is unnecessary. Content correctness still needs separate checks.
- B. Incorrect: the schema constrains structure only. A well-formed summary can still misstate the ticket, so faithfulness needs evals or review.
- C. Incorrect: an enum restricts which labels are possible, not which label is right for the ticket. A wrong but valid priority passes the schema.
- D. Incorrect: the token limit is independent of the grammar. If generation stops at
max_tokens, the JSON can be cut off mid-object.
2.Check stop_reason before you parse
The schema guarantee holds only when the response finishes normally. In two situations the output may not match your schema. In a refusal (stop_reason: "refusal"), the refusal takes precedence over the schema constraints. In a truncation (stop_reason: "max_tokens"), the output may be incomplete. Both arrive as HTTP 200 responses, so a parser that only checks the status code will read either one as a success.
Here is a concrete failure. An invoice-extraction job runs with max_tokens=512. Most invoices fit, but every few hundred requests a long one stops partway through a string, and json.loads raises an "Unterminated string" error. Patching the text by closing the open quote and brackets would produce valid JSON that silently leaves out the remaining line items. Loosening the schema doesn't help either, because the text was still cut off. The fix belongs earlier in the code: read stop_reason first. Treat max_tokens as an incomplete result, then retry with a higher max_tokens or split the job into smaller pieces. Treat model_context_window_exceeded the same way.
if response.stop_reason == "max_tokens":
# Response was truncated
print("Response was cut off at token limit")
# Consider making another request to continue| stop_reason | Meaning | Parser action |
|---|---|---|
| end_turn | Claude completed its response naturally | Parse and validate |
| max_tokens | Response reached your max_tokens limit | Do not parse as final; retry with a higher limit or a smaller scope |
| model_context_window_exceeded | Response filled the model's context window | Treat as truncated; do not parse as final |
| refusal | Claude declined to respond | Skip parsing; read stop_details; content may be empty |
| tool_use | Claude is calling a tool | Read the tool_use block's input, not a text block |
A refusal needs its own branch. The content array may be empty. A refusal can also arrive mid-stream after some output has been produced, and that partial output should be discarded. stop_details gives a category and an explanation. The explanation text is not stable, so show it to a user but never parse it. How you retry on a fallback model is covered in integration resilience. For parsing, the rule is that a refusal never reaches your JSON reader.
Enum casing is a smaller gap, but it shows up quickly in production. The value may differ from your schema only in capitalization, usually in the first letter of a word after a space. A switch statement that compares strings exactly will send that value to its default case. Normalize case before you dispatch on it.
Checkpoint 4 of 9· Check yourself
While you stream a structured-output extraction, part of a JSON object arrives. The response then finishes as HTTP 200 with stop_reason "refusal" and a populated stop_details. What should your parsing layer do?
A refusal takes precedence over the schema, so any partial output is incomplete and must never reach the JSON reader. The explanation text is not stable, so you can display it but should never parse it.
“A refusal can arrive before any output, or mid-stream after partial output. In either case, treat any partial output as incomplete and discard it.”Source: platform.claude.com
Checkpoint 5 of 9· Exam question
An invoice-extraction job uses a JSON schema. About 1 in 300 responses fail in json.loads with an 'Unterminated string' error, and each failing response is very long. Logs show the request used max_tokens=512. What is the most appropriate defensive fix in the parsing layer?
Correct answer: B — Check stop_reason before parsing and treat max_tokens as incomplete, then retry with a larger limit or narrower scope.
- A. Incorrect: closing the open string and brackets produces a parseable object, but its last value is a half-written fragment that looks valid and is wrong. The cut-off itself goes unaddressed and bad invoice data flows downstream.
- B. Correct: a
max_tokensstop reason means generation was cut off, so the JSON is incomplete by definition. Detecting that before parsing and retrying with more room or a smaller task deals with the cause of the failures. - C. Incorrect: temperature controls sampling randomness, not how much an invoice contains or how long the output runs. Long invoices still need more tokens than 512 and will keep being truncated.
- D. Incorrect:
additionalPropertiesonly controls which extra keys are allowed. The failure is an unterminated string caused by truncation, which is a syntax error thatjson.loadsrejects before any schema check runs.
3.Why the first request with a new schema is slower
Constrained decoding needs a grammar, and the API builds that grammar from your schema. JSON outputs and strict tools share one pipeline: each input_schema is compiled into a grammar, and the compiled grammar is cached for up to 24 hours after its last use. The first request that uses a new or changed schema therefore pays the compile cost. Later requests with the same schema reuse the cached grammar.
This explains a pattern you may see after a deploy. The first call with a large, newly edited schema is noticeably slower than the calls after it, and nothing fails. That is compilation, and it is expected. It does not mean the schema is invalid, that the conversation history is being rebuilt, or that requests are being rate limited. Two practical consequences follow. Every schema edit triggers a fresh compile. A schema that has not been used for a day will be compiled again.
The cache also affects compliance. Compiled schemas are stored separately from message content, and those cached schemas do not receive the same protections for protected health information (PHI) as prompts and responses do. Strict tool use is HIPAA eligible, but that eligibility stops at the schema: PHI must stay out of property names, enum values, const values and pattern regexes, because those end up in the cached copy. It belongs only in message content, which is where the HIPAA safeguards apply. A schema with a diagnosis code as an enum value breaks this rule; a schema with a generic diagnosis string field, filled in through the prompt, does not.
Checkpoint 6 of 9· Check yourself
After a deploy that edits a large strict-tool schema, the first request using it takes noticeably longer than usual. It succeeds with schema-valid input, and the requests after it with the same schema are fast again. What explains the slow first call?
Constrained decoding needs a grammar built from the schema. A new or changed schema is compiled on its first use, and the compiled grammar is cached, so later requests with the same schema skip that cost. A slow first call is expected and does not point to an invalid schema, throttling or a history rebuild.
“Strict tool use compiles tool input_schema definitions into grammars using the same pipeline as structured outputs.”Source: platform.claude.com
Checkpoint 7 of 9· Exam question
After a release, the first request for a new, complex JSON schema takes noticeably longer than later requests using the same schema. Nothing is failing. How should the team interpret this?
Correct answer: C — Expected behavior: the first use of a schema incurs grammar compilation, and compiled grammars are cached for later calls.
- A. Incorrect: a first-call latency bump does not indicate invalidity; truly unsupported schema features return a 400 error instead.
- B. Incorrect: the API is stateless in the sense that the client sends history each turn, and attaching a schema does not trigger a special history rebuild.
- C. Correct: constrained decoding compiles the schema into a grammar on first use and caches it, so one slower first call is normal and stable schemas benefit from reuse.
- D. Incorrect: schema use does not place requests in a separate slower queue, and rate limiting would appear as 429 errors.
4.Validation in code: the SDK helpers and your own models
The API accepts only a subset of JSON Schema, so SDK helpers rewrite your schema before sending it. client.messages.parse() takes a Pydantic model and makes these changes: it removes unsupported constraints such as minimum and maxLength, copies each removed constraint into the field's description, adds additionalProperties: false to every object, and filters string formats down to the supported list. Claude sees only the simplified schema. A helper that validates responses then checks the reply against your original schema, including every constraint it removed.
This makes the validation step necessary rather than redundant. For a field declared with minimum: 100, the API only enforces "integer". The description tells Claude about the minimum, but nothing in decoding prevents a value of 40. The helper's own validation catches it. transform_schema() performs the same rewrite without sending a request, so you can inspect or edit the schema first.
One modelling mistake gets past every check. A field typed as a plain dict is sent as an object with empty properties. Combined with additionalProperties: false, the only value Claude can produce is {}. If you know the keys, declare a nested model.
Agent workflows put the result in a different place. The Agent SDK runs an agent that can work through several turns of tool use before it answers, so it does not return one response the way messages.create does. Its query() function is an async generator: you iterate it with async for message in query(...), passing the prompt and a ClaudeAgentOptions whose output_format holds a json_schema and your schema. The loop yields messages as the agent works. The final one is a ResultMessage, and that is the message that carries the data as structured_output. Check is_error before you read it. If the session gives up after repeated schema failures, a single-shot query() raises after yielding an error such as error_max_structured_output_retries. Validate the payload against your own type before you use it. The snippet below sits inside that loop, and message is each item the loop yields.
if (
isinstance(message, ResultMessage)
and not message.is_error
and message.structured_output
):
# Validate and get fully typed result
plan = FeaturePlan.model_validate(message.structured_output)safeParse returns a success flag instead of throwing an exception. The code can branch on parsed.success and send a failed payload to a retry or an error path, so a bad payload does not crash the loop.
Checkpoint 8 of 9· Fill the gap
An Agent SDK loop has already skipped error results. Before downstream code uses the payload, it must be checked against the FeaturePlan Pydantic model. Which method completes the line?
if (
isinstance(message, ResultMessage)
and not message.is_error
and message.structured_output
):
# Validate and get fully typed result
plan = FeaturePlan. ? (message.structured_output)model_validate checks structured_output against your own type and returns a typed FeaturePlan. That is the validation step the section says you should run before using the payload. model_json_schema generates the schema you send, model_dump serializes an existing model, and model_construct builds an instance without validating it.
Source: code.claude.com5.Parsing JSON out of free text
Sometimes the JSON arrives inside ordinary text. You might want Claude to reason in prose before it answers, or you might be on a path without a schema. In those cases the parser has to find the JSON before it can read it. Begin with the prompt: give the exact format, keys and allowed values. How to write that prompt is covered in prompt revision. Then design the extraction so it holds up when the text around the JSON varies.
These techniques work on every current model:
- Ask Claude to wrap each JSON object in named XML tags, then use a regex to pull out each tagged block. This holds up even when a response contains several JSON objects and searching for the first
{would fail. - Pull out the text inside a fenced json block when Claude uses one.
- Set a stop sequence that ends generation right after the JSON, so no trailing commentary follows it. Check
stop_reason == "stop_sequence"and readstop_sequenceto see which one fired.
Older guides teach prefilling the assistant turn with { to skip the preamble. Current models (Opus 5.5, Sonnet 5.5, Haiku 5.5) return a 400 for any request that ends with an assistant message, so prefill is no longer an option. When downstream code needs the shape guaranteed, use output_config.format instead of a free-text fallback. If you parse free text anyway, run the result through the same validation model you would use for structured outputs, because nothing upstream checked it.
Checkpoint 9 of 9· Check yourself
Your report job on Sonnet 5.5 has Claude reason in prose and then emit several separate JSON objects in one response. The parser slices from the first "{" to the last "}", and it keeps failing. Which extraction approach holds up here?
Named XML tags give each JSON object clear boundaries, so a regex can pull out each one even when there are several. Searching for braces can't do that. Prefill returns a 400 on current models. A stop sequence after the first object would cut off the others. strict applies to tool definitions, not to free text.
“you can also have Claude output each JSON item in specified tags for future extraction.”Source: platform.claude.com
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Always valid: No JSON parsing errors”
↩︎ What a schema guarantees, and what it leaves to you“The output might not match your schema because the refusal message takes precedence over schema constraints.”
↩︎ Check stop_reason before you parse“Retry with a higher max_tokens value to get the complete structured output.”
↩︎ Check stop_reason before you parse“Structured outputs use constrained sampling with compiled grammar artifacts.”
↩︎ Why the first request with a new schema is slower“Remove unsupported constraints (for example, minimum, maximum, minLength, maxLength)”
↩︎ Validation in code: the SDK helpers and your own models“The SDK sends a dict field as an object with empty properties, so Claude can only return {} for it.”
↩︎ Validation in code: the SDK helpers and your own models“Structured outputs guarantee schema-compliant responses through constrained decoding:”
↩︎ Key concept“Type safe: Guaranteed field types and required fields”
↩︎ Exam trap 1“The output might be incomplete and not match your schema.”
↩︎ Exam trap 2“Claude receives a simplified schema, but a helper that validates responses still enforces every constraint in your code.”
↩︎ Exam trap 4“Structured outputs don’t guarantee the capitalization of string enum and const values”
↩︎ Prediction - 2.
“Without strict mode, Claude might return incompatible types ("2" instead of 2) or omit required fields”
↩︎ What a schema guarantees, and what it leaves to you“Tool name is always valid (from provided tools or server tools)”
↩︎ What a schema guarantees, and what it leaves to you“Strict tool use compiles tool input_schema definitions into grammars using the same pipeline as structured outputs.”
↩︎ Why the first request with a new schema is slower“The API caches compiled schemas separately from message content, and these cached schemas do not receive the same PHI protections as prompts and responses.”
↩︎ Why the first request with a new schema is slower“Tool schemas are temporarily cached for up to 24 hours since last use.”
↩︎ Exam trap 3 - 3.
“In either case, treat any partial output as incomplete and discard it.”
↩︎ Check stop_reason before you parse“The text is not stable, so display it rather than parse it.”
↩︎ Check stop_reason before you parse“A refusal can arrive before any output, or mid-stream after partial output. In either case, treat any partial output as incomplete and discard it.”
↩︎ Checkpoint - 4.
“A single-shot query() throws after yielding an error result, such as”
↩︎ Validation in code: the SDK helpers and your own models“The result message contains structured_output with validated data”
↩︎ Validation in code: the SDK helpers and your own models - 5.
“Claude emitted one of your stop_sequences.”
↩︎ Parsing JSON out of free text“max_tokens | The response reached your max_tokens limit. | Raise max_tokens or continue the response.”
↩︎ Checkpoint - 6.https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistencyOfficial docs
“Precisely define the output format you want using JSON, XML, or custom templates”
↩︎ Parsing JSON out of free text - 7.
“You can instruct Claude to output JSON in XML tags to make it easy to collect afterward for more complex prompts.”
↩︎ Parsing JSON out of free text“return a 400 for a request that ends with an assistant message.”
↩︎ Parsing JSON out of free text“you can also have Claude output each JSON item in specified tags for future extraction.”
↩︎ Checkpoint