Structured Outputs
Advanced 13 min read Structured Outputs

Schema Design for LLMs

Contracts that generation can keep

LLM-friendly schemas are flat, optional-heavy, and enum-driven. Designing your contract to the strengths of generation — not to the dreams of a relational DBA — raises compliance and unblocks the product.

schema designflatnullableenumcomplianceoptional
Prerequisites: JSON Schemas
Before we start

What you will learn

  • Design flat, nullable, enum-driven schemas
  • Split over-stubborn schemas into stages
  • Measure schema compliance over time
Introduction

What is this?

Schema design for LLMs is a constraint problem: models comply best with flat objects, bounded enums, few required fields, and clear nullable semantics. Deep nesting and required grids tempt failure. Design starts from what the task needs, then trims to what generation reliably emits.

Motivation

Why do you need it?

  • Compliance is a hidden quality axis — a 'perfect' schema the model can't fill is worthless.
  • Flat beats nested for generation; nullable beats pseudo-values.
  • Enum discipline gives downstream switch/UI typed branches.
  • Measured compliance (validated % of calls) drives schema evolution honestly.
Think about it

Mental model

Imagine

A survey that people actually finish

Think of

LLM-friendly schema

Length, requiredness and nesting decide completion. A 3-question optional survey gets answered; a 40-question required matrix gets abandoned or, worse, answered with junk. LLM schemas follow the same psychology — keep fields few, optional and clear.

Mechanics

How it works

  • Start from the task's true output needs; drop decorative fields.
  • Prefer flat objects; nest only where meaning demands it.
  • Mark fields optional unless the consumer cannot proceed without them.
  • Use enums for closed sets; allow refusals/unknown via 'other'.
  • Measure compliance; refactor schema when it strays from realistic output.

Schema design flow.

Needs
Draft
Probe
Tune
Measure
Real world

In production

  • Extraction endpoints ship flat optional-rich schemas and exceed compliance budgets.
  • Tool-call schemas keep required args minimal for higher tool-invoke success.
  • Enums feed typed UIs and routing without runtime string parsing.
Guidelines

Best practices

  • Default optional; require only what breaks if missing.
  • One level of nesting max for high-compliance tasks.
  • Include an explicit unknown/other enum branch.
  • Track compliance percent per schema in the eval suite.
Watch out

Common mistakes

  • Mirroring the DB schema verbatim (wide, deep, all-required).
  • Rejecting valid model nuances because enums are too narrow.
  • Never remeasuring compliance as data evolves.
Root cause analysis

Common issues

Error
Near-universal enum violations
Root cause

Enum doesn't cover real outputs

Fix

Sample actual outputs and extend/reshape the enum.

Error
Required fields spammed with placeholders
Root cause

Unfillable requirement

Fix

Make it optional and nullable; log absence instead of forcing lies.

When things break

Debugging tips

  • Compliance drops after data change → enum or required set is stale; revisit.
  • Models fill fake values for required fields → they prefer a lie to nothing; make it optional + nullable.
  • Nested failures localize → too deep; flatten.
Interviews

Interview checkpoint

Practice

Hands-on lab

Nested Schema Validation by Hand
30 min · intermediate
In progress
Objectives
  • Write a schema as required fields plus types
  • Validate outer and nested objects with one checker
  • Catch missing keys before type mismatches

Nested Schema Validation by Hand

30 min · intermediate

0/3 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

Weighing compliance, the better default is…

2

Models prefer fabricating a required value to leaving a field null.

Go deeper

Official documentation

Structured output best practices (OpenAI)
docs