Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Developer Platform 22 Oct 2026
One change · api

structured-outputs changedbuild-with-claude/structured-outputs

Nearest release: v2.1.308, published 2 hours after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here
Lines+14added
Lines−20removed
From line 110 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits21to this page, all time

The whole hunk

from line 110, old and new numbered
/
lines
from line 110
110110 
111111 Claude returns JSON like this in the response's text content block:
112112 
113 ```json Output
113 ```text Output wrap
114114 {
115115 "name": "John Smith",
116116 "email": "[email protected]",
from line 148
148148 
149149 Claude returns JSON like this in the response's text content block:
150150 
151 ```json Output
151 ```text Output wrap
152152 {
153153 "name": "John Smith",
154154 "email": "[email protected]",
from line 788
788788 
789789 Claude returns JSON like this in the response's text content block:
790790 
791 ```json Output
791 ```text Output wrap
792792 {
793793 "name": "John Smith",
794794 "email": "[email protected]",
from line 826
826826 
827827 Claude returns JSON like this in the response's text content block:
828828 
829 ```json Output
829 ```text Output wrap
830830 {
831831 "name": "John Smith",
832832 "email": "[email protected]",
from line 2594
25942594Structured outputs use constrained sampling with compiled grammar artifacts. This introduces some performance characteristics to be aware of:
25952595 
25962596* **First request latency:** The first time you use a specific schema, there is additional latency while the grammar compiles.
2597 
25982597* **Automatic caching:** Compiled grammars are cached for 24 hours from last use, making subsequent requests much faster.
2598* **Cache invalidation:** The cache is invalidated if you change the JSON schema structure or, when using both structured outputs and tool use, the set of tools in your request. Changing only `name` or `description` fields does not invalidate the cache.
25992599 
2600* **Cache invalidation:** The cache is invalidated if you change:
2601 
2602 * The JSON schema structure
2603 * The set of tools in your request (when using both structured outputs and tool use)
2604 * Changing only `name` or `description` fields does not invalidate the cache
2605 
26062600### Prompt modification and token costs
26072601 
26082602When using structured outputs, Claude automatically receives an additional system prompt explaining the expected output format. This means:
from line 2703
27092703 
27102704Claude maintains its safety and helpfulness properties even when using structured outputs. If Claude refuses a request for safety reasons:
27112705 
2712* The response has `stop_reason: "refusal"`
2713* You'll receive a 200 status code
2714* You'll be billed for the tokens generated
2715* The output might not match your schema because the refusal message takes precedence over schema constraints
2706* The response has `stop_reason: "refusal"`.
2707* You'll receive a 200 status code.
2708* You'll be billed for the tokens generated.
2709* The output might not match your schema because the refusal message takes precedence over schema constraints.
27162710 
27172711A property that asks for the model's thinking or step-by-step reasoning might lead to a `reasoning_extraction` refusal. Ask for a short explanation instead. See [Keep reasoning in thinking blocks](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).
27182712 
from line 2714
27202714 
27212715If the response is cut off because it reached the `max_tokens` limit:
27222716 
2723* The response has `stop_reason: "max_tokens"`
2724* The output might be incomplete and not match your schema
2725* Retry with a higher `max_tokens` value to get the complete structured output
2717* The response has `stop_reason: "max_tokens"`.
2718* The output might be incomplete and not match your schema.
2719* Retry with a higher `max_tokens` value to get the complete structured output.
27262720 
27272721**Enum value casing**
27282722 
from line 2794
28002794 
28012795**Incompatible with:**
28022796 
2803* **[Citations](https://platform.claude.com/docs/en/build-with-claude/citations):** Citations require interleaving citation blocks with text, which conflicts with strict JSON schema constraints. Returns 400 error if citations enabled with `output_config.format`.
2804* **Message prefilling:** Incompatible with JSON outputs
2797* **[Citations](https://platform.claude.com/docs/en/build-with-claude/citations):** Citations require interleaving citation blocks with text, which conflicts with strict JSON schema constraints. The API returns a 400 error if citations are enabled with `output_config.format`.
2798* **Message prefilling:** Prefilling is incompatible with JSON outputs.
28052799 
28062800<Tip>
28072801 **Grammar scope:** Grammars apply only to Claude's direct output, not to tool use calls, tool results, or thinking tags (when using [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)). Grammar state resets between sections, allowing Claude to think freely while still producing structured output in the final response.
Feedback