Claude structured outputs can reject a schema before a model runs, or accept the request and still leave a constraint unenforced. On November 8, 2026, I sent nine one-rule schemas to seven model setups and asked each model to break the rule. The most useful result wasn't a winner: it was the difference between an HTTP 400 and a valid JSON response that failed validation.
I build Octomind, where a verification step also depends on schema-shaped answers.
The short answer: Claude's Messages API accepts a JSON Schema in output_config.format with type: "json_schema". Anthropic documents numeric bounds, string lengths, maxItems, and recursive schemas as unsupported; unsupported keywords should fail with 400. In our test, however, both Claude models accepted the maxLength case, and Haiku broke it in two of three runs. Keep the API schema simple, validate every response in your code, and treat results as specific to the model and route you tested.
What do Claude structured outputs guarantee?
They constrain Claude's direct text response to JSON matching a supported schema. They don't turn every JSON Schema keyword into an API-enforced rule, and they don't make the values factually correct. Anthropic's Structured Outputs documentation (checked November 2026) distinguishes JSON output formatting from strict tool use: use output_config.format for the answer your application consumes; strict: true on a tool validates the tool's input instead.
Structured outputs are generally available on the Claude API; Anthropic announced GA on February 4, 2026, with expanded schema support in its Developer Platform announcement (2026). The current Messages API docs list all API models as supported (checked November 2026).
A 400 means the request or schema was refused before generation. A 200 can still be a refusal (stop_reason: "refusal") or incomplete output (stop_reason: "max_tokens"); Anthropic says either can fail the schema. Check stop_reason before parsing, then validate the JSON. The docs also say message prefilling is incompatible with JSON outputs, so don't prepend { as a workaround.
We learned the routing lesson in production: our verification step asked for a schema answer, but one account routed it to a model whose provider could not enforce schemas. Every call failed with 400, and the user saw the same answer repeated. We changed the eligible model choices for that job.
How do I send a Claude JSON Schema?
Put the schema under output_config.format on a Messages API request. The Python SDK and raw HTTP request use the same field; the SDK's messages.parse() helper can also take a Pydantic model as output_format and transform it. The raw API's canonical parameter is output_config.format, not the old beta output_format field.
Python SDK, using a simple object schema:
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=256,
messages=[{"role": "user", "content": "Extract the ticket status: open"}],
output_config={"format": {"type": "json_schema", "schema": {
"type": "object",
"properties": {"status": {"type": "string", "enum": ["open", "closed"]}},
"required": ["status"], "additionalProperties": False,
}}},
)
if response.stop_reason != "end_turn":
raise RuntimeError(f"Claude stopped with {response.stop_reason}")
text = next(block.text for block in response.content if block.type == "text")The equivalent raw HTTP request uses the same body shape:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model":"claude-sonnet-5-5","max_tokens":256,
"messages":[{"role":"user","content":"Extract the ticket status: open"}],
"output_config":{"format":{"type":"json_schema","schema":{
"type":"object","properties":{"status":{"type":"string","enum":["open","closed"]}},
"required":["status"],"additionalProperties":false
}}}
}'The example follows Anthropic's documented request shape; it wasn't run as a tutorial command. If you define types with Pydantic, Anthropic's client.messages.parse(output_format=MyModel) can transform the model schema before sending it. Anthropic compiles schemas into grammars. The first use of a schema adds compile latency; compiled grammars are cached for 24 hours after last use, and changing the schema structure invalidates that cache. (Docs checked November 2026.)
Which JSON Schema keywords does Claude reject?
Anthropic's current list is clear: recursive schemas, numeric constraints such as minimum and maximum, minLength and maxLength, and array limits other than minItems: 0 or 1 are unsupported. It also rejects external $ref and objects where additionalProperties isn't false. Unsupported features should return 400 with details. See the supported and unsupported keyword list in Anthropic's docs (2026).
Supported features include basic types, scalar enum, const, anyOf, local $ref, common string formats, and simple regex patterns. There are limits inside those categories: complex enums and external references are out, allOf with $ref is unsupported, and regex lookarounds and backreferences aren't supported. “JSON Schema supported” therefore means a documented subset, not the whole specification.
Our request tests exposed a wrinkle in the docs. Anthropic lists maxLength as unsupported, but our two tested Claude models accepted that request with HTTP 200. Haiku's response broke the 20-character limit twice; Sonnet's passed all three pressure prompts. This is consistent with different enforcement behavior, but three runs don't prove how the backend enforced decoding. The practical rule is to move length checks into your validator even when the API accepts the schema.
The same nine rules across seven model setups
We used nine schemas, each with one constraint, and a prompt asking for an output that violated it. We ran each cell three times on November 8, 2026, and checked parseable JSON against JSON Schema Draft 2020-12 with a format checker. This is a small conflict test, not a broad reliability benchmark. The columns are exact model and route setups; Gemini and gpt-oss ran through OpenRouter with require_parameters: true.
| Constraint | Haiku 5.5 | Sonnet 5.5 | GPT-6 Luna | GPT-6.1 Sol | Gemini 3.8 Flash | gpt-oss-120b | DeepSeek Flash |
|---|---|---|---|---|---|---|---|
enum | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
pattern | 3/3 | 3/3 | 3/3 | 3/3 | broke 2/3 | 3/3 | 400 |
maxLength | broke 2/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
minimum + maximum | 400 | 400 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
maxItems | 400 | 400 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
format: date | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
additionalProperties: false | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
anyOf | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
recursive $ref | 400 | 400 | 3/3 | 3/3 | 3/3 | 3/3 | 400 |
3/3 means the response passed validation in all three runs; broke 2/3 means it returned valid JSON that failed the schema twice; 400 means all requests for that cell were rejected. A green cell is what happened under pressure in these runs, not proof of the provider's implementation. For OpenRouter routes, the serving provider can vary: our Gemini calls came from Google, and gpt-oss calls from several hosts.
Each cell counts runs that passed the schema, of 3 (so
1/3 is the table's broke 2/3). Source: author's conflict test, run 8 November 2026.
The loud failure was Claude rejecting minimum/maximum, maxItems, and recursive $ref. The more dangerous result was a successful request with a broken answer: Haiku exceeded maxLength in 2/3 runs, while Gemini 3.8 Flash returned abc123 against the pattern in 2/3. A green 3/3 here only says the model followed the conflicting prompt in these three attempts.
DeepSeek's deepseek-flash rejected every json_schema request with HTTP 400 and This response_format type is unavailable now. Switching to json_object and putting the schema in the prompt produced 26/27 valid answers in our 27 fallback calls; the one failure returned an error object that didn't match the requested schema. DeepSeek's JSON Output docs (checked November 2026) describe valid JSON output, not JSON Schema enforcement. Keep a validator after that mode.
Does a schema that held mean the data is right?
No. A held schema guarantees the shape, and the model fills that shape with whatever fits. Every conflict prompt asked for a value the schema could not hold, so each passing answer had to replace the user's value with something else. These are first-run answers from the same 8 November test, plus the DeepSeek JSON-mode fallback:
| The prompt said | What came back |
|---|---|
status is pending (allowed: open, closed) | "open" from all seven setups that answered (six schema runs plus DeepSeek JSON mode) |
SKU is abc123 (pattern AAA-0000) | "ABC-0123", "SKU-9482", "ABC-1234" |
| score is 9 (allowed 1 to 5) | 5 from four setups (GPT-6 Luna, GPT-6.1 Sol, Gemini, DeepSeek JSON mode), 1 from gpt-oss-120b |
| due "next Tuesday afternoon" (format date) | "1970-01-01" (Haiku 5.5), "1234-05-06" (GPT-6.1 Sol), "2026-11-10" (GPT-6 Luna) |
value is the text unknown (integer or null) | null from every setup |
None of these is an error a validator can catch: each one is valid JSON that matches the schema. The fix is in the schema design. Give the model a legal way to say it can't comply, for example a nullable field plus a "status": "cannot_comply" enum branch with a reason string, and check values against the source, not only the shape. DeepSeek's JSON mode, which had no schema to hold it, once answered {"error": "Cannot produce a record matching the schema..."} instead. That was the honest answer, and our schema had no room for it.
How do I make one schema portable across providers?
Keep only the shared structure in the provider schema, then enforce rules in your own validator. Our sample points to three useful edits: turn a small fixed numeric range into an enum; move string length, array length, and regex checks to code; and flatten or bound recursive data for Claude. Keep additionalProperties: false and list every property as required for OpenAI strict mode. For an optional value, include null in its type rather than omitting the property.
| API or route | Request shape | Portability note |
|---|---|---|
| Anthropic Messages API | output_config.format: {type: "json_schema", schema} | Anthropic documents a subset; unsupported constraints can 400. |
| OpenAI Chat Completions | response_format: {type: "json_schema", json_schema: {name, strict: true, schema}} | Strict mode requires all properties in required and additionalProperties: false; see OpenAI's Structured Outputs guide (checked November 2026). |
| Gemini (Google AI Studio) | Native API: a JSON Schema in generationConfig (responseJsonSchema); OpenAI-compatible endpoint: response_format | Google's OpenAI-compatibility guide shows structured output through response_format; see the API reference and compatibility guide, checked November 2026. In our run, the pattern constraint broke 2 of 3 times. |
| DeepSeek native API | response_format: {type: "json_object"} | It requests valid JSON, not schema enforcement. Put the schema in the prompt, then validate. |
| OpenRouter | Chat Completions response_format as above, plus provider.require_parameters: true | Support is per serving endpoint; OpenRouter says enforcement can vary. See its Structured Outputs docs (checked November 2026). |
Run a validator after parsing even if the provider says “strict.” This Python check reports the first schema errors rather than quietly returning invalid data:
import json
from jsonschema import Draft202012Validator, FormatChecker
data = json.loads(text)
validator = Draft202012Validator(schema, format_checker=FormatChecker())
errors = list(validator.iter_errors(data))
if errors: raise ValueError(errors[0].message)Keep the schema and parser in agreement. We once allowed basis: null in the schema while our parser rejected an empty basis; that made a valid-by-schema answer fail downstream. We fixed it by encoding the same two-branch rule with anyOf. For a CI job that consumes JSON, see structured output in CI; the structured-output docs also distinguish capability from enforcement.
When is JSON mode enough?
Use JSON mode when you only need syntactically valid JSON and will check the object yourself. Use schema-constrained output when the chosen route supports the schema features you need; use local validation either way. A provider can enforce the shape and still leave business rules such as “score is between 1 and 5” to your application.
Octomind's octomind run --schema follows that same boundary: it fails before the provider call if the selected model lacks structured-output capability, then asks the caller to validate the returned object. We also changed our schema fallback after forced-tool calls on GLM routes missed required fields in 4 of 13 calls and retried the billed call up to three times: the library now makes one upstream call and fails closed with the validator's reason. That one-call rule lives in octolib, the model library Octomind uses; it isn't a promise that every provider enforces every keyword.
For a Claude-only request, start with Anthropic's subset and inspect its 400 errors. For a multi-provider request, use the intersection for structure, move fine-grained constraints to a shared validator, and test the exact model endpoint with adversarial prompts before trusting it with a downstream write.
Related reading: Claude API pricing · DeepSeek API pricing



