OpenAI Structured Outputs guide
Official documentation for schema-constrained model responses and the implementation considerations around them.
← Back to Compute College
Compute College
Structured outputs and output contracts
Use schemas, required fields, and deterministic validation to make AI responses usable by software.
Plain-English definition
A structured output contract states the shape a model response must have: fields, types, allowed values, required evidence, and behavior when information is missing. A schema can help a provider constrain generation, but production code still needs to validate the result before using it. Structure separates “the model produced text” from “the application received data it can safely act on.”
Memory trick: A schema checks shape. Evidence checks truth. Permissions check authority.
Why it matters
Free-form prose is useful for people but brittle for downstream software. A missing field, invalid enum, or invented value can trigger a failed workflow, an unnecessary retry, or a human review. Strong output contracts make failure visible and can reduce the number of model calls needed to turn an answer into usable work.
- Required fields expose incomplete answers instead of letting missing information look like success.
- Enums and typed values make deterministic checks possible before a tool or database write.
- Short, bounded outputs reduce unnecessary generation tokens and make latency easier to predict.
Simple example
A ticket classifier can require `{category, requestedOutcome, evidence}`. `category` must be one of four values, `requestedOutcome` may be empty when absent, and `evidence` must quote the input. If validation fails, the application routes to review rather than calling the model repeatedly with the same ambiguity.
- The schema describes shape, not truth: evidence still needs to be checked against the input.
- Optional fields should have an explicit missing-value convention.
- A validator can reject malformed JSON without asking the model to “try harder” automatically.
Example figures are illustrative calculations, not current quoted market prices.
Current example
Structured output reference
OpenAI documents structured outputs as a way to make model responses conform to developer-supplied schemas. The application remains responsible for validating meaning, handling refusal or incomplete cases, and deciding whether an output is safe to use.
Source discipline: the reference explains the concept or method; it is not a substitute for measuring a production workload under its actual provider, model, and data conditions.
Common mistake
Valid JSON is not necessarily a correct answer. A model can return perfectly shaped data with an invented value, unsupported citation, or unauthorized action. Validate both syntax and evidence before a response crosses a system boundary.
Practical takeaway
What you can do with this
Write an output contract for one workflow. List required fields, allowed values, missing-data behavior, and the checks that run before a downstream action. Measure malformed responses, semantic failures, retries, and tokens before and after the contract.
- Developers: validate every field used by code or tool calls.
- Product teams: decide which missing values should pause the workflow.
- Operators: alert on schema-failure and retry-rate changes after prompt or model updates.
Decision check: if the model returns a valid shape but an unsupported value, does the system catch it before it causes a user-visible or irreversible result?
Compute College track
Prompt & Context Engineering
Step 6 of 18: Structured outputs and output contracts