15. Structured Output: Stop Parsing Vibes

What this section is for

As soon as your AI output feeds software (UI rendering, database writes, tool calls), you need structure. Free text is great for conversation. It’s a liability for apps.

This section teaches you how to stop parsing vibes and start using contracts:

• JSON-first prompting,
• schemas that are hard to break,
• graceful handling of invalid outputs,
• enums and constraints to reduce ambiguity,
• validation and user-facing error surfacing.

Mental model: output is untrusted input

Even if the model is “usually right,” outputs are untrusted input for your code. They can be:

• malformed (invalid JSON),
• incomplete (missing fields),
• wrong type (string instead of number),
• semantically wrong (hallucinated facts),
• blocked/refused (safety behavior),
• overlong (too many bullets, too much text).

Structured output doesn’t magically fix semantic correctness, but it makes failures detectable and manageable.

Why JSON-first is the default for apps

JSON-first is popular because it’s:

• parseable: standard libraries exist everywhere,
• validatable: JSON Schema gives you a contract,
• renderable: UIs can display it safely,
• testable: you can write golden tests and regression tests,
• versionable: schema versions can evolve over time.

A practical workflow for structured output

1. Define the schema (small and strict).
2. Prompt for JSON only (no prose, no markdown).
3. Parse the output as JSON.
4. Validate against the schema.
5. Handle failure explicitly: retry/repair/fallback.
6. Log versions (prompt + schema) and outcome categories.

This is the core loop you’ll reuse for RAG, tool calling, and production apps.

Section 15 map (15.1–15.5)

• 15.1 JSON-first prompting
• 15.2 Designing schemas that are hard to break
• 15.3 Handling partial/invalid JSON gracefully
• 15.4 Using enums and constraints to reduce ambiguity
• 15.5 Validating outputs and surfacing errors to users

Where to go next

• Start with 15.1
• Then go to 16. Tool calling