AI for developers
Structured Outputs JSON Schema: What OpenAI, Claude and Gemini Accept, Ignore or Reject
In short
Structured outputs JSON Schema support is a subset on all three APIs, and the subsets differ. Claude rejects unsupported keywords with a 400 error, Gemini accepts several length and uniqueness keywords and ignores them, and OpenAI lists what it does not yet support and requires every field to be required. A schema moved between vendors needs a check.
Which structured outputs JSON Schema keywords does each API support?
A schema that passes on one API can fail loudly on another, or pass quietly and stop enforcing a rule you were counting on. The table lists the keyword groups where the three documentation sets disagree most.
| Keyword group | Claude | OpenAI | Gemini |
|---|---|---|---|
| String length: minLength, maxLength | Not supported, returns a 400 error | Not in the supported string list, which names only pattern and format | Accepted but not enforced; the server ignores them |
| Number bounds: minimum, maximum | Not supported, returns a 400 error | Supported, with multipleOf and the exclusive bounds | minimum and maximum are listed, both inclusive |
| Array size | minItems of 0 or 1 only | minItems and maxItems | minItems, maxItems and prefixItems; uniqueItems and contains are ignored |
| Recursive schemas | Not supported | Supported, with a root reference written as # | Allowed through $defs and $ref, but the page says to make the recursive reference optional or nullable |
| Composition | anyOf and allOf with exceptions; oneOf and not are rejected | anyOf supported; allOf, not, if, then, else and the dependent keywords are not yet supported | The page's own example uses anyOf for a conditional result |
What happens when a keyword is not supported?
Claude fails the request. The guide says an unsupported feature gets a 400 error with details. Its SDK helpers can soften that: they strip the unsupported constraints, append each one to the field's description so the model still sees it, add additionalProperties false to every object and keep only the string formats on the supported list.
Gemini takes the opposite route for the keywords it ignores. minLength, maxLength, minProperties, maxProperties, uniqueItems, contains, minContains and maxContains are not enforced by the constrained decoding, and the page tells you to validate those rules in your own code. A response can look compliant and still be too short or contain duplicates.
OpenAI's guide names the composition keywords it does not support yet and notes that fine-tuned models lose more, including the string, number and object constraints. The section I read does not say what the error looks like, so test a schema before you rely on a keyword.
Which objects must be closed, and which fields must be required?
OpenAI is the strictest about shape. Every field has to be listed as required, every object needs additionalProperties set to false, and the root has to be an object, not an anyOf. The guide points out that a discriminated union from Zod produces a root anyOf and will not work as it stands.
Claude also demands additionalProperties false on objects, which has a consequence the guide spells out: the model can only return keys you list. An object with empty or missing properties can come back only as an empty object, so a free-form map has no place in a schema.
How large can the schema be?
OpenAI publishes size ceilings: up to 5,000 object properties in total, 10 levels of nesting, 120,000 characters across property, definition, enum and const names, and 1,000 enum values.
Claude measures complexity differently. Per request it allows 20 strict tools, 24 optional parameters across all strict tool and JSON output schemas combined, and 16 parameters that use unions such as anyOf or a type array. Exceeding any of them returns a 400 error that says the schema is too complex.
Gemini gives no figures. Its limitations list warns that very large or deeply nested schemas may be rejected and suggests flattening nested objects and trimming enums and unions.
What can still produce a response that does not match?
A valid schema does not guarantee a conforming answer. On Claude, a safety refusal comes back with stop_reason refusal and a 200 status, and the text may not fit the schema. Hitting max_tokens can also leave the JSON incomplete.
OpenAI constrains completed output that is not a refusal and says your code still has to handle refusals, incomplete responses and API errors, and enforce business rules that a schema cannot express. Gemini likewise tells you to validate values yourself.
Some costs sit outside the schema. Claude compiles a grammar the first time it sees a schema, which adds latency on that first request, and keeps the compiled grammar for 24 hours from last use. Changing output_config.format also invalidates the prompt cache for that conversation. OpenAI says only fine-tuned models pay a first-request penalty. OpenAI also returns keys in the order of the schema.
What should you change before moving a schema between vendors?
Treat the strictest vendor as the baseline and add the rest as application code.
- Drop string-length and number-bound keywords for Claude, and move them into descriptions or a validator.
- List every field as required and close every object if the target is OpenAI.
- Remove recursion before sending a schema to Claude, and make the recursive link optional for Gemini.
- Keep a validator for the keywords Gemini ignores, because they will not fail.
- Count strict tools, optional parameters and unions against the Claude limits before you deploy.
What else do people ask?
Is a JSON Schema enough to guarantee the answer is correct?
No. All three vendors describe schema adherence as a constraint on format. They tell you to validate values and business rules in your own code.
Which API is the most forgiving about schema keywords?
It depends on what forgiving means. Gemini accepts the most keywords without error, but it ignores several of them. Claude rejects what it cannot enforce, and OpenAI requires a stricter shape up front.
Sources
- Claude Platform docs, Structured outputs, fetched 2026-11-20
- OpenAI API docs, Structured outputs, fetched 2026-11-20
- Gemini API docs, Structured output, fetched 2026-11-20
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. This page compares the three vendors' documentation, which I read on 20 Nov 2026. I did not send schemas to any of the APIs for it, so it reports documented behaviour, not tested behaviour. It does not cover tool-call schemas beyond the Claude limits, prices or model-specific differences. Found a mistake? Tell me.