# Structured Output

Structured output constrains or validates model responses against a defined machine-readable shape so software can process them more safely.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-26
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/structured-output/>)

## What 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.

## Why 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.

## When 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.

## How it works

1. Design a minimal schema with precise names, types, allowed values, optionality, and uncertainty states.
2. Provide the schema and relevant context through a supported structured-output or tool interface.
3. Constrain generation where possible and parse the response without executing embedded content.
4. Validate syntax, semantics, permissions, references, and business invariants in deterministic code.
5. Handle refusal, truncation, invalid output, retries, version changes, and safe fallbacks explicitly.

## A 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/structured-output/#visualization-structured-output>)

## Sources

1. [Structured Model Outputs](<https://developers.openai.com/api/docs/guides/structured-outputs>) — OpenAI · Official documentation
2. [JSON Schema Specification](<https://json-schema.org/specification>) — JSON Schema · Technical specification

## Related topics

- [JSON](<https://wiki.soroush.uk/topic/json/>)
- [Prompt Engineering](<https://wiki.soroush.uk/topic/prompt-engineering/>)
- [Tool Calling](<https://wiki.soroush.uk/topic/tool-calling/>)
