Structured Output Schema Design 2026: Production Patterns + The 5 Schemas That Break LLMs

**The pattern:** A flat schema with 5 top-level fields outperforms a nested schema with 5 fields organized 3 levels deep, even when the information content is identical.

**Why:** Per Instructor at jxnl.github.io/instructor and Pydantic's structured output research at docs.pydantic.dev, nested schemas force the LLM to track multiple levels of context simultaneously. Flat schemas reduce cognitive load + improve completion accuracy. Field accuracy on flat schemas is typically 10-25% higher than on equivalent nested ones.

**The fix:** Flatten where possible. `{user_name, user_email, user_signup_date}` beats `{user: {name, email, signup_date}}`. The minor verbosity loss is worth the accuracy gain.

**The exception:** When nesting genuinely models real structure (e.g., line items in an invoice — each line item has product + quantity + price as a unit), keep the nesting. Don't flatten into `line_item_1_product`, `line_item_1_quantity`, `line_item_1_price` — that's worse.

**The pattern:** Schemas with all-required fields outperform schemas with optional fields. The LLM works harder to fill required fields; it skips optional fields more easily.

**Per OpenAI structured outputs at platform.openai.com:** OpenAI's strict mode literally requires all fields in the schema to be marked required. The pattern is to make every field required and use explicit null / 'unknown' sentinel values instead of optional fields.

**Implementation:** Instead of optional `customer_phone`, use required `customer_phone` with type `string | null` and explicit instruction: 'Use null if phone not in source material.' Forces the LLM to consider every field; reduces silent omissions.

**Per Pydantic at docs.pydantic.dev and Zod at zod.dev:** both libraries support this pattern via explicit nullable types. The validation layer accepts null but tracks it explicitly rather than letting absence pass silently.

**The pattern:** Fields that should be one of a small set of values should be typed as enums, not free-text strings. Per JSON Schema specification at json-schema.org, `enum: ['high', 'medium', 'low']` constrains LLM output to those exact values.

**Why it matters:** Without enum constraint, LLMs generate variants — 'high', 'High', 'HIGH', 'High priority', 'h', 'top priority'. Each variant breaks downstream code that expects exact-match. Per Instructor at jxnl.github.io/instructor, enum-typed fields have near-100% downstream-code compatibility; free-text categorical fields have 60-85%.

**The provider-side enforcement:** Per OpenAI structured outputs at platform.openai.com and Anthropic's tool use at docs.anthropic.com, modern constrained-decoding implementations enforce enum membership at the token level — invalid values are impossible by construction.

**The exception:** When the set of possible values is genuinely unbounded (e.g., user-supplied tag names), use string. When it's bounded but rapidly evolving (e.g., product categories), consider enum vs. validated-string trade-off.

**The pattern:** Each schema field's description should include 1-2 examples of valid + invalid values. Embedded examples outperform separate few-shot examples for structured output tasks.

**Why:** Per Pydantic at docs.pydantic.dev and Instructor at jxnl.github.io/instructor, the LLM sees the field description in the schema context during generation. Examples embedded there are referenced at the moment of decision. Separate few-shot examples are at higher distance + less referenced.

**Implementation:** Field `customer_priority` description: 'Priority level. Valid: high, medium, low. Examples: VIP customer = high. Standard subscriber = medium. Free trial = low.' The embedded examples disambiguate edge cases the field name + enum alone don't capture.

**Per Anthropic at docs.anthropic.com:** the JSON Schema `description` field is the primary input channel for guiding LLM behavior on each field. Treat it as a mini-prompt for that specific field.

**Anti-pattern 1 — Deeply nested optional fields.** Multi-level nesting with optional fields at each level. The LLM frequently omits entire branches of the tree. Per Instructor at jxnl.github.io/instructor, this is the most-common production failure.

**Anti-pattern 2 — Free-text where enum belongs.** 'Severity: low' vs. 'Severity: a bit low maybe' — both pass schema validation; downstream code breaks on the second. Per JSON Schema at json-schema.org, use enum constraints for categorical data.

**Anti-pattern 3 — Ambiguous field names.** `value`, `data`, `info`, `result` — the LLM has to guess what should go there. Per Pydantic at docs.pydantic.dev, descriptive names (`customer_satisfaction_score`, `support_ticket_summary`) reduce ambiguity-driven errors.

**Anti-pattern 4 — Date/time as free-text.** 'When was this signed?' → LLM produces 'last Tuesday' or 'mid-2024' or '2024-03-15'. Per OpenAI structured outputs at platform.openai.com, use ISO 8601 string with explicit format constraint or numeric epoch timestamp. Validate via Zod at zod.dev or Pydantic at docs.pydantic.dev datetime validators.

**Anti-pattern 5 — Numbers as strings without type validation.** Quantities, prices, percentages — if not typed as number, LLM may return '$5.99' or '5.99 dollars' or 'about 5'. Per Google's Gemini structured output at ai.google.dev and Anthropic at docs.anthropic.com, type as number; let the constrained decoder enforce.

Naive 'respond in JSON' prompts: Field omissions. Type drift. Enum variants ('high' vs. 'High' vs. 'top priority'). Date format chaos. Nested-field accuracy drops. Downstream code breaks on 15-40% of LLM responses. Retry logic everywhere.
Schema design principles + constrained decoding: Flat where possible. All-required fields with explicit null. Enums for categorical. Embedded examples per field. Number + datetime types properly. 95-99% downstream-compatible LLM responses. Retry logic mostly unused.