Structured / JSON Output
Category: Output control & formatting
Structured output constrains the model to emit machine-readable data — usually JSON matching a schema — so responses integrate reliably with code. Modern APIs can enforce the schema so every response parses.
What it is
Structured / JSON OutputStructured output makes the model return data in a strict, parseable format rather than free prose, so downstream code can consume it directly. The most common form is JSON that conforms to a specified schema. Beyond just asking for JSON in the prompt, current provider APIs offer schema-enforced modes (structured outputs / JSON mode / tool schemas) that constrain decoding so the result is guaranteed to be valid and to match the requested shape.
This turns the model into a reliable component of a software pipeline: field names, types, and enums are predictable, eliminating brittle parsing of natural-language responses.
When to use
- The output feeds code, a database, or another API and must parse deterministically.
- You need specific fields, types, or an enumerated set of values.
- Free-text responses are too variable to consume programmatically.
- You are building extraction, classification, or function-calling workflows.
How it works
- Define the target schema: field names, types, required-ness, and allowed values.
- Use the provider's structured-output / JSON mode (or a tool schema) to constrain decoding when available.
- Instruct the model to return only the structured object, with no prose around it.
- Validate the parsed result against the schema and handle any violations.
Illustrative structure
The structure specifies a shape and asks for it exactly: "Return a JSON object with keys 'category' (one of A|B|C) and 'confidence' (0–1). Respond with JSON only." Ideally the same schema is passed to the API's structured-output mode so decoding is constrained.
Pitfalls
- Prompt-only "please return JSON" without schema enforcement can still yield invalid or wrapped JSON.
- Over-nested or huge schemas raise error rates and token cost.
- Extra prose, markdown fences, or trailing commentary break naive parsers — demand raw output.
- Always validate; even schema-constrained output can contain semantically wrong values.
Frequently asked questions
What is Structured / JSON Output?
Structured output constrains the model to emit machine-readable data — usually JSON matching a schema — so responses integrate reliably with code. Modern APIs can enforce the schema so every response parses.
When should you use Structured / JSON Output?
The output feeds code, a database, or another API and must parse deterministically. You need specific fields, types, or an enumerated set of values. Free-text responses are too variable to consume programmatically. You are building extraction, classification, or function-calling workflows.
What are common pitfalls of Structured / JSON Output?
Prompt-only "please return JSON" without schema enforcement can still yield invalid or wrapped JSON. Over-nested or huge schemas raise error rates and token cost. Extra prose, markdown fences, or trailing commentary break naive parsers — demand raw output. Always validate; even schema-constrained output can contain semantically wrong values.
Sources
Related techniques
← All prompt engineering techniques
Apply Structured / JSON Output with Prompeteer, the Agentic Contextual AI Platform →