# Claude Structured Outputs: JSON Schema Limits and a Cross-Provider Test

> Claude structured outputs use JSON Schema, but supported keywords differ by API. See our seven-model test and a portable validation pattern.

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)](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) 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)](https://claude.com/blog/structured-outputs-on-the-claude-developer-platform). 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:

```python
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:

```bash
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)](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations).

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.

![Nine schema constraints against seven model setups: most cells held 3 of 3, Haiku 5.5 passed maxLength 1 of 3, Gemini 3.8 Flash passed pattern 1 of 3, and amber cells were rejected with HTTP 400](/blog/claude-structured-outputs/schema-keyword-matrix.svg)
_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)](https://api-docs.deepseek.com/guides/json_mode/) 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)](https://developers.openai.com/api/docs/guides/structured-outputs).                                                                                           |
| 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](https://ai.google.dev/api/generate-content) and [compatibility guide](https://ai.google.dev/gemini-api/docs/openai), 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)](https://openrouter.ai/docs/guides/features/structured-outputs).                                                                                                                  |

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:

```python
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](/blog/octomind-non-interactive-ci-automation); the [structured-output docs](/docs/usage/11-structured-output) 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](/blog/claude-api-pricing) · [DeepSeek API pricing](/blog/deepseek-api-pricing)
