Schema Design for LLM Output: Field Order, Enums, and Honest Escape Values

When you ask a model for structured output, the schema is not just a parsing contract. It is also part of the prompt, and the model reads it. Small schema choices change both how often the output validates and how good the content inside it is.

Order fields so reasoning comes before the verdict

Models generate tokens left to right. If your schema lists "verdict" before "explanation", the model must commit to an answer before it has written anything that supports it, and the explanation then rationalizes whatever came first. Put free-text reasoning or evidence fields first and the decision fields after them:

{
  "evidence": ["..."],
  "reasoning": "...",
  "verdict": "approve | reject | needs_review"
}

This is the same principle as asking for step-by-step work before the final answer, expressed as structure. Test it on your own data rather than assuming the gain; for easy classification the difference may be negligible, for judgment-heavy fields it is often visible.

Prefer closed sets, and include an honest escape value

Use enums for anything with a finite set of valid values, and describe each value in the field description, not just its name. Then add a value for "none of these". Without one, the model is forced to pick a wrong category when the input does not fit, and that error looks identical to a confident correct answer downstream. Values such as "other", "unknown", or a nullable field give you a signal you can route to review.

Be careful that the escape value does not become the lazy default. If more than a small fraction of outputs land there, your enum is missing real categories, and the distribution of "other" items is the best source for the next version of the schema.

Keep it flat, small, and explicit

• Limit nesting. Deeply nested objects and arrays of objects raise the odds of a malformed or truncated structure. If a flat list of records plus an ID reference does the job, use it.
• Mark optionality deliberately. Decide for each field whether it is required, nullable, or absent, and say so in its description. "Optional" fields the model fills with plausible inventions are a common source of silent errors.
• Constrain formats in text and in validation. Say "ISO 8601 date, e.g. 2026-03-14" in the description, then validate it in code anyway. Descriptions improve compliance; they do not guarantee it.
• Version the schema. Add a schema_version you control, so stored outputs can be interpreted after the schema evolves.

Closing point

Treat the schema as a reviewed artifact with tests: a handful of inputs that should hit each enum value, one that should hit the escape value, and one with missing information that should yield nulls instead of inventions. When output quality drops, the schema belongs on the list of suspects, right next to the prompt text.