Structured Output & JSON Schema Errors
Every JSON, schema, and structured-response error across providers — with the fix.
22 documented errorsErrors in this category
Model response can't be parsed as JSON despite response_format: json_object.
response_format.json_schema.strict is true but schema violates strict-mode constraints.
Every object in strict mode requires additionalProperties: false.
Strict mode requires every property listed in the 'required' array.
Schema nested deeper than 5 levels — strict mode's max.
response_format conflicts with tools + tool_choice configuration.
finish_reason='length' mid-JSON, leaving unparseable partial output.
Schema uses a JSON Schema feature OpenAI's structured outputs doesn't yet support.
tool_use input_schema is not valid JSON Schema draft 2020-12.
Combined tool input_schema exceeds practical token limits.
Assistant prefill '{' followed by generation that doesn't complete valid JSON.
Without additionalProperties: false, model may return fields not in schema.
You're on an older Claude model that doesn't support the structured output API.
Response doesn't conform to responseSchema despite responseMimeType being set.
responseSchema is set but responseMimeType is not 'application/json'.
responseSchema uses oneOf, unsupported in Gemini's OpenAPI 3.0 subset.
Recursive schemas via $ref have limited support in Gemini.
Response cut off due to maxOutputTokens ceiling.
Model returned a string not in the specified enum list.
Model filled a field with a plausible-sounding but invented value not grounded in source.
Value close to an enum choice but not exact — 'medium priority' instead of 'medium'.
Nested object partially filled; some required subfields missing.
Related pillar guides
Related blog posts
Frequently asked questions
What's the difference between JSON mode and structured outputs?
JSON mode (response_format: json_object) guarantees the response parses as valid JSON — any JSON. Structured outputs (response_format: json_schema with strict: true) also guarantees the JSON conforms to your specific schema. Structured outputs is strictly better where available.
Why does OpenAI strict mode require additionalProperties: false everywhere?
It's a design constraint of the enforcement engine. Without it, the model could add fields not in your schema, which would break the strict guarantee. If you find this restrictive, drop strict: false and validate client-side with Zod or Pydantic instead.
How do I model optional fields in OpenAI strict mode?
Use type unions with null: `{ "type": ["string", "null"] }` and include the field in the required array. The field must be present in the response, but its value can be null. Verbose but reliable.
Can I use anyOf/oneOf across all providers?
OpenAI supports both (with strict mode constraints). Anthropic supports both. Gemini's OpenAPI 3.0 subset supports anyOf but not oneOf. If you need portable schemas, use discriminated unions via anyOf with a discriminator field, or move the union logic to client-side validation.
Why is my JSON response truncated?
Almost always max_tokens too low. Structured schemas with many fields need generous max_tokens. Check response.stop_reason ('length' or 'max_tokens' means truncation), increase max_tokens, or split into smaller extractions.
Does the strict mode apply to nested objects?
Yes, recursively. Every object at every level must have additionalProperties: false and every field listed in required (with null unions for optional). This is why schemas that were fine in permissive mode fail when you flip strict: true.
How do I detect when a JSON response is hallucinated vs. grounded in source?
Add a source-quote pattern: for every extracted value, require a companion field with the verbatim quote from the source text. Post-validate that the value appears in the quote. See G8 Chapter 6 for the pattern.