Structured Output
Structured output constrains or validates model responses against a defined machine-readable shape so software can process them more safely.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/structured-output/
01What it means
Structured output is the practice of having a model return data that conforms to a schema, grammar, or typed contract rather than unrestricted prose. Implementations may use constrained decoding, tool arguments, or validation and retry. Syntactic conformance means fields and types are shaped correctly; it does not establish that values are true, authorized, or semantically valid.[1][2]
- 01Minimal schemaNames, types, allowed values, optionality, uncertainty
- 02Model generationStructured-output, grammar, or tool interface
- 03Parse safelyTreat returned content as data, never executable code
- 04Validate syntaxRequired fields, types, ranges, and schema version
- 05Validate semanticsPermissions, references, business rules, and truth
- 06Handle failureRefusal, truncation, retry, fallback, and review
A syntactically valid object can still contain fabricated, unsafe, unauthorized, or semantically impossible values.
02Why it matters
Reliable shapes make model output easier to integrate with interfaces and workflows and reduce brittle text parsing. Clear schemas also force teams to name missing, uncertain, and escalation states instead of pretending every request has a confident answer.
03When to use it
Use structured output when downstream software needs fields, classifications, extracted values, or proposed actions. Free text remains suitable for human-facing drafts. Never let schema-valid output bypass domain validation, authorization, or confirmation for consequential actions.
04How it works
- Design a minimal schema with precise names, types, allowed values, optionality, and uncertainty states.
- Provide the schema and relevant context through a supported structured-output or tool interface.
- Constrain generation where possible and parse the response without executing embedded content.
- Validate syntax, semantics, permissions, references, and business invariants in deterministic code.
- Handle refusal, truncation, invalid output, retries, version changes, and safe fallbacks explicitly.
05A practical example
A feedback tool asks a model for theme IDs, source quote IDs, and an uncertainty field using a JSON Schema. The application rejects unknown IDs, checks that quoted text matches the source, and sends uncertain cases to a researcher rather than accepting merely valid JSON.
06Where it breaks
Constrained decoding can reduce but not eliminate malformed responses and may limit expressive tasks. A valid object can contain fabricated or harmful values. Complex schemas consume context, evolve over time, and can encourage teams to automate decisions that still require judgment.
Common mistakes
- Treating schema validity as factual or business validity.
- Using loose string fields where enums, identifiers, or explicit null states are needed.
- Executing generated code, queries, or tool arguments without validation and authorization.
- Ignoring refusals, partial output, truncation, and schema version migration.
07Sources
- Structured Model OutputsOpenAI · Official documentationStructured Model Outputs
- JSON Schema SpecificationJSON Schema · Technical specificationJSON Schema Specification