Source: OpenAI Structured Outputs Guide
OpenAI API guide on Structured Outputs vs JSON mode: strict json_schema, supported schema subset, numeric limits, refusals and truncation.
Contents
- What: official API documentation page
- Author/publisher: OpenAI
- Date: living document; read 2026-11-14
- Original: Structured Outputs
Summary
Structured Outputs constrains completed, non-refusal output to a supplied JSON Schema, via text.format: {type: "json_schema", strict: true, schema} in the Responses API (response_format in Chat Completions) or via strict function tools. JSON mode (json_object) only guarantees syntactically valid JSON. The guide documents the schema subset, size limits and the cases the app must still handle.
Key claims
- Supported types: string, number, boolean, integer, object, array, enum, anyOf. Supported keywords include string
pattern/format, numericminimum/maximum/multipleOf, arrayminItems/maxItems. Unsupported:allOf,not,if/then/else, dependent schemas. Fine-tuned models additionally do not support string length/pattern/format, numeric bounds,patternPropertiesor array length keywords. - Root must be an object (not
anyOf); every field must berequired(optional = union withnull);additionalProperties: falseeverywhere; keys come out in schema order. - Recursion supported through
$ref: "#"or self-referencing$defs. - Limits: 5,000 object properties, 10 nesting levels, 120,000 characters of names/enum/const values, 1,000 enum values total.
- First request with a new schema has extra latency (schema processing), later ones do not.
- Refusals arrive as a
refusalcontent part; truncated output showsstatus: "incomplete"withmax_output_tokens. - JSON mode requires the word “JSON” in the context (API error otherwise); without an instruction the model may emit whitespace until the token limit. JSON mode is not schema-guaranteed.
- Without guidance for unfit input, the model may hallucinate values to fill the schema.
- Use function calling to connect tools; use
text.formatto structure the reply to the user.