---
title: "Structured Outputs"
description: "Constraining LLM responses to JSON-schema shapes — objects, enums, arrays — for data extraction and classification, with streaming and tool-based variants."
section: "concepts"
type: "concept"
created: "2026-08-30"
updated: "2026-08-30"
confidence: "high"
tags: ["llm-fundamentals", "context-engineering", "patterns"]
canonical: "https://pyweb.dev/wiki/structured-outputs"
---
# Structured Outputs

Often the thing you want back from an LLM is **not text but an object**: extracting multiple properties from unstructured input (PDFs, comments, documents) is one of the most powerful and business-relevant LLM use cases, alongside classification into enums/categories.


```json
{
  "name": "verdict",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": { "pass": {"type": "boolean"}, "reason": {"type": "string"} },
    "required": ["pass", "reason"],
    "additionalProperties": false
  }
}
```

## Variants
- **Object generation:** pass a JSON schema, receive a typed object (data extraction from PDFs and other unstructured sources).
- **Enum generation:** constrain output to a fixed set of enumerated values (classification, sentiment, routing).
- **Array generation:** schema with multiple items for batch extraction.
- **Streaming objects:** instead of waiting for the whole object, stream it field-by-field as generation proceeds.
- **Tool-based structuring:** reuse [tool calling loop](/wiki/tool-calling-loop) infrastructure — declare a tool whose arguments are your schema and force the model to call it — to get the same shape guarantees without a dedicated structured-output API.

## Why It Matters
Structured outputs are the bridge between probabilistic text generation and deterministic application code: they make LLM output consumable by databases, validators, and pipelines. The pattern pairs naturally with [evals skills](/wiki/evals-skills) — schema conformance is cheap to verify automatically, a rare machine-checkable oracle.

## Failure Modes

| Symptom | Root cause | Fix |
|---|---|---|
| Schema violated at runtime | Model improvises fields | Strict schema mode + validation retry on parse failure |
| Over-constrained schema chokes output | Too many required fields | Required only what downstream code reads; everything else optional |
| Silent parse fallback | JSON extracted with regex | Fail loudly on malformed output; route to retry, never to guess |

## Rule of Thumb

Schema conformance is the cheapest deterministic oracle available -
prefer it over any judge when the property is checkable.

## Related
[llm message protocol](/wiki/llm-message-protocol), [tool calling loop](/wiki/tool-calling-loop), [model provider abstraction](/wiki/model-provider-abstraction), [evals skills](/wiki/evals-skills), [generator evaluator loop](/wiki/generator-evaluator-loop).

---

## Agent Navigation

cluster: llm-fundamentals (8 pages) | betweenness: 25.6

### References (outbound)
- [Tool Calling Loop](https://pyweb.dev/wiki/tool-calling-loop.md)
- [Evals Skills](https://pyweb.dev/wiki/evals-skills.md)
- [LLM Message Protocol](https://pyweb.dev/wiki/llm-message-protocol.md)

### Referenced by (inbound)
- [Eval Taxonomy](https://pyweb.dev/wiki/eval-taxonomy.md)
- [LLM App Improvement Ladder](https://pyweb.dev/wiki/llm-app-improvement-ladder.md)

### Evidence (verified primary sources)
- raw/aihero-video/wiUXxKeFSz8JTwQvmZ7ut029nJ23PevCst8ylkrCHtTU.md (internal workspace doc)
- raw/aihero-video/NR9LollfJgzuMq02zxZn6nnhQjMVcTQ2vkhvc8Xz2025U.md (internal workspace doc)
- raw/aihero-video/uygTjLE2W4XQs5Qla01MRI1arhqTtui2gOCQqFMlIlEs.md (internal workspace doc)
- raw/aihero-video/ZxadOHgUN02s99h3Jhp01TwEcbgKVmWUkA9qnwOM3eMI4.md (internal workspace doc)
- raw/aihero-video/PG15cq802CeSluIc6YM7CV927SX01MbOUpQ01FBVXN8WlI.md (internal workspace doc)

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt