Course contentsShow
← AI Engineering
Lesson 794 of 1,88619. Structured Output and ValidationFree lesson

Schema Documentation for LLMs

Add descriptions, examples, and constraints to schemas to improve LLM understanding and output quality.

Schema Documentation for LLMs

What you'll learn: How to enhance schemas with descriptions, examples, and constraints to help LLMs produce higher-quality structured output.

Why Documentation Matters

Think of schema documentation like labeling containers in a kitchen. A jar marked "Sugar" is clearer than one labeled just "Powder"—similarly, LLMs perform better when schemas include rich context about what each field represents and expects.

When you define schemas for structured output, the LLM receives not just field names and types, but also your documentation. This guidance dramatically improves output accuracy, especially for ambiguous or domain-specific fields.

The Three Pillars of Schema Documentation

1. Descriptions
Add clear explanations for each field. Instead of just email: str, write:

email: str  # User's primary contact email address in standard format

2. Examples
Show the LLM what valid data looks like. For a phone_number field, provide: "Example: +1-555-123-4567". This sets expectations far better than type hints alone.

3. Constraints
Spell out business rules explicitly: "Must be between 1 and 5 stars", "ISO 8601 date format required", or "Cannot exceed 280 characters". While validators enforce rules programmatically, documentation helps the LLM generate compliant output from the start.

Practical Impact

Well-documented schemas reduce validation failures because the LLM understands intent, not just structure. For nested objects, document relationships between fields. For enums, explain when to use each option. For optional fields, clarify what makes them appropriate to include or omit.

The more context you provide in your schema, the less the LLM has to guess—and guessing is where errors creep in.

Key Takeaway: Rich schema documentation (descriptions, examples, constraints) transforms schemas from mere type definitions into clear instructions, significantly improving LLM output quality and reducing validation errors.