Structured Outputs
by OpenAI
Guaranteed schema-conformant JSON — and the schema subset that actually works.
Overview
OpenAI's Structured Outputs guide documents the API feature that forces a model response to conform to a JSON Schema you supply, so downstream code can parse it without defensive validation. The guide states the two guarantees plainly — type-safe output matching the schema, and refusals that are detectable programmatically rather than arriving as prose — then separates Structured Outputs from the older JSON mode, which only guarantees syntactically valid JSON and nothing about its shape. Implementation is shown two ways: SDK helpers that derive the schema from a Pydantic model in Python or a Zod schema in JavaScript, and the raw configuration for everything else, using a text format block of type json_schema with strict set to true and the schema inline. Worked examples cover chain-of-thought responses with typed steps, extracting structured records from unstructured text, generating recursive UI trees, and moderation classification. Edge cases get their own sections: detecting a refusal, handling responses truncated by max tokens or a content filter, and consuming structured output while it streams. A supported-schemas section spells out which JSON Schema constructs are accepted and which are not, which is the part practitioners actually hit — unsupported patterns such as open-ended string-keyed maps fail with confusing errors rather than clear ones. Availability starts at GPT-4o, with gpt-5.6 recommended for new work and JSON mode named as the fallback for older models. Samples appear in JavaScript/TypeScript, Python, Go and curl.
At a Glance
- Topic
- Frameworks
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~25-35 minute read; reference docs, self-paced
- Provider
- OpenAI
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Force API responses to conform to a JSON Schema you define
- ✓Derive schemas automatically from Pydantic models or Zod schemas
- ✓Detect and handle model refusals programmatically instead of parsing prose
- ✓Recognise which JSON Schema constructs the strict subset actually supports
- ✓Handle truncated responses caused by max tokens or content filters
- ✓Consume structured output incrementally while the response is streaming
- ✓Choose between Structured Outputs and legacy JSON mode per model
Highlights
- •Schema conformance is a guarantee here, not a prompt-engineering hope
- •Refusals surface as a distinct field, so a safety decline never masquerades as malformed JSON
- •First-class Pydantic and Zod helpers remove the hand-written schema step entirely
- •The supported-schemas section is the part to read first — practitioners repeatedly report that unsupported constructs like string-keyed maps fail with confusing error messages
- •This is the machinery behind strict mode in function calling, so the same limits apply to tool arguments
- •Independent testing suggests constrained decoding can shift model behaviour rather than being free, so treat it as reliable formatting rather than improved reasoning
Who It’s For
Best For
- ✓Engineers extracting structured records from unstructured text
- ✓Developers who need type-safe LLM responses in production pipelines
- ✓Teams debugging strict-mode schema rejections
Prerequisites
- •Working knowledge of JSON Schema
- •Python with Pydantic, TypeScript with Zod, or an equivalent stack
- •An OpenAI API key and a basic request loop to modify
FAQ
What is Structured Outputs?
OpenAI's reference for forcing model output to match a JSON Schema you supply, so downstream code can parse it without defensive validation. It covers Pydantic and Zod helpers, programmatic refusal detection, streaming, truncation edge cases, and the supported-schema limits. The same machinery backs strict mode in function calling, so the constraints carry over to tool arguments.
Is Structured Outputs free?
Structured Outputs is free to access.
What level is Structured Outputs for?
Structured Outputs is aimed at a intermediate audience. Recommended background: Working knowledge of JSON Schema, Python with Pydantic, TypeScript with Zod, or an equivalent stack, An OpenAI API key and a basic request loop to modify.
How long does Structured Outputs take?
Expect roughly ~25-35 minute read; reference docs, self-paced. Most learners work through it at their own pace.
What will I learn from Structured Outputs?
You'll learn: Force API responses to conform to a JSON Schema you define; Derive schemas automatically from Pydantic models or Zod schemas; Detect and handle model refusals programmatically instead of parsing prose; Recognise which JSON Schema constructs the strict subset actually supports; Handle truncated responses caused by max tokens or content filters; Consume structured output incrementally while the response is streaming; Choose between Structured Outputs and legacy JSON mode per model.
Topics
Sources
This page was written from 3 sources, 2 on domains other than developers.openai.com.