Structured outputs

How it works

Structured outputs means asking the API to make the model's reply conform to a schema you supply, usually JSON Schema. When the provider enforces it during generation, the reply is valid JSON with the required fields and types.

There is a difference between JSON mode (valid JSON of any shape), schema-enforced output (the shape you specified) and simply asking for JSON in the prompt (no guarantee). Providers support different subsets of JSON Schema. A schema guarantees shape, not that the values are correct.

Use it whenever code consumes the reply. Keep schemas simple, and still validate values such as dates, IDs and enums in your own code.

Worked example

Illustrative: with a schema requiring {"total": number, "currency": string}, extracting from an invoice returns {"total": 1249.5, "currency": "EUR"} every time, instead of sometimes 'The total is EUR 1,249.50' in prose your parser can't read.

Common mistakes

• 1Assuming schema-valid means correct; values can still be wrong or invented.
• 2Using schema features the provider doesn't support, which can cause errors or be ignored.
• 3Setting max output tokens too low, so long JSON is cut off and fails to parse.