| name | structured-output |
| description | Stable structured JSON output for agents using strict schemas. Use when you need deterministic JSON responses, schema validation, or streaming JSON object assembly (generateObject/streamObject-style) with retry-and-repair loops. |
Structured Output (Strict JSON)
Implement stable, schema-validated JSON outputs for agents. Use this when responses must be valid JSON, match a schema exactly, and be reliable under retries/streaming.
Core Workflow
- Define a strict schema (JSON Schema or Pydantic).
- Generate JSON-only output (no prose).
- Validate output against schema.
- If invalid, run a repair pass with a minimal error-focused prompt.
- For streaming, emit incremental JSON with a deterministic assembly buffer.
Prompt Pattern (Non-Streaming)
Use a strict system instruction and a minimal user prompt. Always require JSON only. Input can be empty; output must still match the schema.
Template:
SYSTEM:
You are a JSON generator. Output ONLY valid JSON that matches the given schema.
Do not include Markdown, comments, or trailing text.
If a field is unknown, use null (unless schema disallows it).
USER:
Return JSON that matches this schema:
<SCHEMA>
Input:
<INPUT>
Prompt Pattern (Streaming)
Use the same schema but ensure the model emits a single JSON object and nothing else. Stream tokens and buffer until a valid JSON parse succeeds.
Implementation References
- JSON Schema + retry/repair loop: see
references/json_schema_patterns.md
- Pydantic models + parsing: see
references/pydantic_patterns.md
- Python examples:
scripts/generate_object.py, scripts/stream_object.py
Guardrails
- Reject non-JSON output immediately; re-prompt with error-only instructions.
- Disallow extra keys unless
additionalProperties is explicitly true.
- Keep schemas small and explicit; prefer enums for constrained values.
- Log schema + error details for debugging (do not expose stack traces to end users).
