Mid · 7 chapters
Schema design for LLMs
Field naming, descriptions as instructions, enums over free text, flat over deeply nested
Poor schemas turn straightforward model calls into brittle parsing, silent misclassification, and expensive retry loops.
Read these first
What you will know
Write field descriptions that function as instructions
Descriptions can constrain behavior beyond the type itself, but ambiguous prose may compete with stronger schema constraints and produce inconsistent outputs.
Replace a free-text field with an enum and measure the improvement
Enums reduce the output space, although they can convert vague prose into confident selection of the wrong category when the vocabulary is incomplete.
Flatten a nested schema and show the model does better
Each additional nesting level adds paths the model must preserve, increasing omission and structural-error rates even when the underlying information is simple.
Trace a failed structured response to the schema constraint or description that induced it
A failure may come from contradictory descriptions, an underspecified type, or a constraint the model cannot satisfy rather than from generation quality alone.
Review a schema and predict which field the model will get wrong
The highest-risk field is often the one with vague semantics, overlapping valid values, or a description that leaves edge cases unresolved.
Chapters
- 1
Naming a schema field
A field name is the token sequence sitting immediately to the left of the value, so it conditions the model before any prose is read: holding the description constant and varying only the name moved a discount field from 96 correct answers in 200 to 188. Names that leave the unit open, and names that assert a fact the source does not establish, produce wrong values that validate perfectly.
- 2
Field descriptions versus system prompts
A description is serialised into the request and applied while the field it sits on is being generated, which is why moving a date rule out of bullet thirty-one and onto six fields took non-ISO output from 9 percent to 0.4 percent. This gives a placement rule you can defend, and an account of what actually happens when a prompt bullet and a description disagree about the same field.
- 3
Sentinel values in descriptions
A description that names a literal — the word unknown, the number zero, a category trigger — invents a type the schema does not have, and nothing downstream can tell the invented value from a real one. Each of these is fixed in the structure rather than in the prose, at a measured cost of about 0.6 points of recall.
- 4
Choosing an enum over free text
A description listing six allowed values is a prior the model usually honours — 1.4% of 3,000 production calls said otherwise — while an enum is a constraint on the tokens the decoder may emit, so the gap is a failure rate against none. The price is paid when the vocabulary is incomplete, because a case fitting no member is assigned to the nearest one with full confidence.
- 5
Folded enums and escape members
An enum whose members answer two different questions loses one of the answers on every response, silently and with no member being wrong on its own — a quarterly report said 62 patches where the split schema says 87. Splitting the dimensions fixes that, and an explicit escape member with a free-text companion turns the vocabulary's blind spot into a countable value.
- 6
Schema nesting depth
On the same 800 documents, a field five levels down came back empty 23.4% of the time against 1.1% for a top-level field, with strict mode guaranteeing that every response validated. Flattening asks for the same fact with none of the structural bookkeeping — and flattening everything trades a model problem for a mapping layer nobody wants to own.
- 7
Predicting a schema's worst field
Given a schema you have not seen and no production data, name the field that will fail most and attach a rate to it — then run the same reading backwards, from a bad response to the constraint or description that induced it. The reflex answer is to blame the only free-text field, and it is usually the wrong one.
External resources
- Schema Key Wording as an Instruction Channel in Structured Generation under Constrained Decodingarxiv.org
Evidence that field names alone shift model behavior under constrained decoding.
- Schema Design • Prabalprabal.ca
A substantive practitioner explainer with concrete Pydantic examples and actionable guidance on structured outputs, schema simplicity, field descriptions, discriminated unions, and decomposing evaluations, despite some overconfident claims.
- Schema-Driven Prompt Design: Letting Your Data Model Drive Your Prompt Structuretianpan.co
Why DB-style normalization is backwards for schemas a model has to fill.
- The guide to structured outputs and function calling with LLMs - Agenta-AIagenta.ai
This is a substantive engineering explainer with concrete JSON Schema and Pydantic examples, explaining validation, predictable field structures, and structured-output mechanics rather than merely promoting Agenta.
- LLM Structure Outputs and Use CasesSwiftUI Animation & Agentic Coding
Walks schema shapes against real extraction tasks, flat vs nested.