XI · Structure & DataMature★★

Structured Output

also known as JSON Mode, Schema-Constrained Generation, Typed Output

Constrain the model's output to conform to a JSON Schema (or similar typed shape).

This pattern helps complete certain larger patterns —

  • used-byTool Use★★— Let the LLM produce typed calls against an external toolkit instead of producing free-form text the surrounding system has to parse.
  • used-byFrozen Rubric Reflection★— Constrain reflection to a fixed, hand-authored rubric of criteria so the reviewer cannot invent new ones each run.
  • used-byDeterministic-LLM Sandwich★— Bracket every LLM call with deterministic checks on both sides.
  • used-byDSPy Signatures★— Specify agent behaviour as declarative typed signatures and modules; compile prompts and few-shot examples automatically against a metric.
  • used-byInput/Output Guardrails★★— Validate inputs before they reach the model and outputs before they reach the user.
  • used-bySOP-Encoded Multi-Agent Workflow★— Encode a human Standard Operating Procedure (roles, ordered phases, standardised hand-off artefacts) into a multi-agent pipeline so that agents communicate through structured documents rather than free-form chat.
  • used-byMobile UI Agent★— Drive a smartphone end-to-end through a small, touch-native action vocabulary (tap, long-press, swipe, type, back, home) over screenshots, as a distinct interaction surface from desktop Computer Use and from web Browser Agents.
  • used-byDual-System GUI Agent★— Split a GUI agent into a decision model that plans and recovers from errors and a grounding model that observes pixels and emits the precise action; route each subproblem to the better-suited model.
  • used-byMultilingual Voice Agent Stack★— Compose a voice agent as a tightly co-located pipeline of speech-to-text, language-aware LLM reasoning, and text-to-speech, where one vendor owns all three so language and dialect propagate cleanly across stages.
  • used-byPerformative Message★★— Inter-agent messages are typed by communicative intent (request, inform, propose, accept, refuse, query) rather than by free-form prose, so receivers can dispatch on act type.

Context

A team has a pipeline where downstream code expects typed data — a JSON object with known fields, the input to a function call, the body of an API request. The language model is asked to produce that object, and the code that consumes it cannot work with prose. The team needs the model's output to validate against a schema, not just look like it does.

Problem

When the model is asked to emit JSON via natural-language instructions alone, the output is close but not quite right in inventive ways: smart quotes instead of straight ones, a stray sentence of explanation before the opening brace, a trailing comma, an extra field the schema does not allow. Strict parsers reject this; permissive parsers smuggle bugs forward. Writing post-hoc fixers turns into a tar pit of regular expressions chasing each new failure mode, and the application picks up a class of "flaky model" bugs that are really shape bugs the team has no clean way to prevent at decode time.

Forces

  • Strict schemas reduce model freedom and recall.
  • Schema evolution is a real concern.
  • Provider implementations of structured output differ in fidelity.

Example

A pipeline that consumes model output as JSON keeps breaking on smart quotes, surprise prose preambles, and trailing commas. Post-hoc parsing is a tar pit. The team defines a JSON Schema, passes it via the provider's structured-output mode, validates the result, and retries on validation failure with a low cap. The 'flaky model' bug class disappears because the model is now constrained to the typed shape at decode time.

Diagram

Solution

Therefore:

Define a JSON Schema (or Pydantic / Zod / equivalent). Pass it to the model via the provider's structured-output mode. Validate the output. Reject and retry on validation failure. Cap retries.

What this pattern forbids. The model cannot return content that does not validate against the schema.

And the patterns that stand alongside it, or against it —

  • alternative-toSchema-Free Output✕— Anti-pattern: parse free-form model output for downstream code instead of using structured output.
  • complementsPlan-and-Execute★★— Plan all the steps once with a strong model, then execute each step with a cheaper model under the plan.
  • complementsStreaming Typed Events★★— Push partial results to the client as typed events as they become available, rather than waiting for the full response.
  • alternative-toHallucinated Tools✕— Anti-pattern: trust the model to invoke only the tools it has been given, then debug calls to functions that do not exist.
  • alternative-toTool Output Trusted Verbatim✕— Anti-pattern: trust whatever tools return without validation, schema enforcement, or trust labels.
  • complementsCode-as-Action Agent★— Have the agent emit a code snippet as its action each step, executed in a constrained interpreter, instead of emitting JSON tool calls; tool composition becomes function nesting and control flow inside the snippet.
  • complementsCode-Switching-Aware Agent★— Treat mixed-language input (e.g. Hinglish in Roman script) as the expected shape, and design tokenisation, language tagging, and tool routing to handle it natively without forcing the user to commit to one language.
  • composes-withPrompt/Response Optimiser★★— At runtime, transform user inputs and model outputs into standardised, template-aligned prompts and responses against predefined constraints, so the agent and its downstream consumers see consistent shapes.
  • complementsCitation Attribution★★— Track and surface, alongside a RAG-grounded answer, which retrieved chunks supported which claims, so the binding between answer span and source survives all the way to the user.
  • complementsDeterministic Control Flow, Not Prompt★— Branching decisions live in deterministic application code while the LLM is invoked at strategic points to produce structured signals that the code branches on.
  • complementsContext Minimization★— Reduce untrusted input to a strictly formatted interface (typed fields, max lengths, allow-listed enums) before it reaches any LLM.
  • complementsLLM Map-Reduce Isolation★— Process each untrusted document in its own sealed sub-agent and merge only structured outputs, so an injection in one document cannot steer the processing of others.
  • complementsMissing max_tokens Cap✕— Anti-pattern: call the model without an explicit max_tokens (or equivalent) so a single call can drain the run's budget on a runaway generation.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

Used in recipes

Used in frameworks

Show 35 more

References

Provenance