How do you shape a JSON schema so a model actually complies with it?

## The schema is a prompt A schema handed to a model is not only a validation contract; it is part of the instruction the model conditions on. Field names, ordering, descriptions and structural complexity all shape what comes back. Two schemas that accept exactly the same set of documents can produce very different compliance rates. Treating the schema as a tunable design artifact — measured, revised, versioned — is what separates a pipeline at 99% first-pass validity from one at 80% that leans on a repair loop to cover the gap. ## Flat beats nested Deep nesting is the most common self-inflicted wound. Every level of nesting is another place to close a brace early, misattribute a field to the wrong parent, or drift on a repeated sub-object. Practical guidance: keep the structure to about two or three levels, and let arrays of small flat objects carry repetition rather than object trees. If a schema needs a fourth level of nesting, it is usually two schemas — decompose the extraction into separate calls rather than asking one generation to hold the whole tree. There is a secondary cost too: a large nested schema occupies a meaningful slice of the input window on every single call, and long schemas compete for attention with the actual task. ## Enums beat free text Any field whose values come from a finite set should be declared as an `enum`. Without one, a model asked for an incoterm will return `"DDP"` on one call and `"delivered duty paid"` on another, and your code inherits a normalization problem forever. With one, the value set is part of the contract, so mismatches are caught mechanically and — where the provider constrains generation against the schema — often prevented outright. When the value set is large (hundreds of tariff codes, say), an enum becomes impractical: it bloats the schema and dilutes attention. The pattern there is a typed string with a `pattern` constraint on the format, plus a lookup against your own reference data as a business-rule check. Format in the schema, membership in the rules layer. ## Discriminated flat objects beat unions This is the highest-leverage rule and the one candidates most often miss. Suppose a freight forwarder handles air, ocean and road shipments, each with genuinely different fields — flight number and airway bill for air, vessel and container number for ocean, trailer and carrier for road. The textbook modelling instinct is a `oneOf` across three object shapes. In practice this is where models fail hardest. Branch selection is implicit, and the model routinely produces a hybrid: an air shipment carrying a container number, or a record satisfying no branch cleanly. The error a validator emits for a failed `oneOf` is also unhelpfully vague — it typically reports that the value matched zero (or more than one) branch, without naming which field caused it, which makes the repair turn much weaker. The fix is to **flatten the union into one object with a discriminator enum**: a single `mode` field taking `air`, `ocean` or `road`, with the mode-specific fields present as optional properties on the one flat object. The schema then accepts a slightly wider set of documents than you strictly want, so you close the gap in the business-rule layer: given `mode == "ocean"`, assert the vessel and container fields are populated and the air-only fields are absent. You trade a little structural precision for a large jump in compliance and a far more actionable error message. ## Required, optional and null Be deliberate about `required`. Marking every field required pushes the model to invent a value rather than leave a genuine unknown out — the schema effectively forbids honesty. Marking almost nothing required means your consuming code faces a combinatorial space of absent fields. The useful middle: require exactly the fields the downstream consumer cannot function without, and for optional-but-known-shape fields prefer an explicit nullable type over silent absence, so "the model looked and found nothing" is distinguishable from "the model never addressed this". Some strict provider modes require every property to be listed as required, in which case nullable types become the way to express optionality. ## Names and descriptions are instructions Descriptive `snake_case` names outperform terse codes: `gross_weight_kg` carries the unit, the concept and the type expectation in one token sequence, where `gw` carries none of them. Use each field's `description` to state the format precisely, including one example where format is unusual — `"six-digit HS heading, digits only, no separators"` prevents the very common `8471.30.01` failure against a six-digit pattern. ## Closing the shape and bounding the size Set `additionalProperties: false` so invented keys are rejected rather than silently ignored, and bound arrays with `maxItems` where a real ceiling exists. Both convert a class of quiet weirdness into a named validation error. ## Measure, then revise The closing discipline: log validation failures by field path, aggregate them, and treat a field that fails disproportionately as a schema-design defect rather than a fact of nature. A single field driving most of your repair traffic is almost always fixable by an enum, a clearer description or a flattening — and fixing it removes an entire generation's worth of cost and latency from every affected request.