Prompt to JSON Schema

Why schemas matter for model output

Asking a language model to reply in JSON and hoping is unreliable: you get prose wrapped around the object, a stray code fence, or a field named differently each time. Structured output modes in the major APIs take a JSON Schema and constrain generation so the response conforms by construction rather than by instruction. The schema stops being documentation and becomes an enforcement mechanism.

additionalProperties is the keyword people forget

Without additionalProperties set to false, a schema silently accepts fields it never described. A typo in an optional property name passes validation and is then ignored at runtime, which is a difficult bug precisely because nothing complains. Several providers require it to be false, along with every property being listed in required, before they will accept a schema for strict structured output at all.

Describe every field

The description on each property is not a comment; the model reads it. A field described as an ISO 8601 date in UTC produces materially more consistent output than the same field with no description. This is the highest-leverage thing in the whole schema and the part most often left empty.

Constrain enums rather than asking politely

Where a value must be one of a fixed set, an enum guarantees it. Instructing the model in the prompt to pick one of three options does not, and the failures are the awkward kind: a plausible fourth value that your switch statement has no branch for. Anything with a known set of valid values belongs in an enum.

Keep it shallow

Deeply nested schemas are harder for models to satisfy reliably and harder for you to validate meaningfully. Two or three levels is usually enough. Where you need more, consider several smaller calls with focused schemas rather than one large one, which also makes retries cheaper when a single section fails.

Validate anyway

Structured output modes are strong but not a guarantee across every provider, model and fallback path. Validate the response against the same schema on receipt. It costs almost nothing and turns a malformed response into a clear error rather than a downstream mystery.