AI Explained · Concept

What are structured outputs?

Structured outputs make a model return data in a shape you define, valid JSON matching a schema, so your code can parse it reliably instead of wrestling freeform text.

The problem they solve

Asking a model to “return JSON” in the prompt mostly works, until it doesn’t. You get a chatty preamble, a markdown ```json fence, a trailing comma, or a field renamed on a whim. Then your parser throws and you’re writing fragile regex to clean it up. Structured outputs fix this at the source: you give the model a schema, and the API constrains generation to it, right field names, right types, valid JSON. With true constrained decoding (OpenAI strict, Gemini responseSchema) the structure is enforced; Anthropic’s tool-schema approach steers strongly but isn’t hard-constrained, and any provider can still truncate at the token limit and cut a response short.

JSON mode vs structured outputs

These get conflated. JSON mode guarantees the output is valid JSON, but not that it matches any particular shape. Structured outputs (schema-constrained) guarantee it matches your schema: the exact fields, types, and required keys you specified. If you need to reliably read result.price as a number, you want schema-constrained structured outputs, not just JSON mode.

How it works across providers

The idea is the same everywhere, supply a JSON Schema, get conforming output, but the API surface differs:

  • OpenAI: a response_format of type json_schema with strict: true.
  • Anthropic: commonly via a tool whose input_schema is your JSON Schema; the model “calls” it with the structured data.
  • Gemini: a responseSchema plus responseMimeType: application/json.

The Structured Output Builder generates all of these from one visual schema, so you don’t have to hand-write each provider’s flavor.

Why it matters

  • Reliable parsing. No defensive string-munging; with constrained decoding the shape is enforced (barring truncation).
  • Fewer retries. You stop re-prompting because the JSON came back malformed.
  • It powers real features. Data extraction, classification, form-filling, and tool-call arguments are all structured-output problems.

Getting good results

  • Describe your fields. A short description per property steers the model far better than the field name alone.
  • Use enums for closed sets. If a status is one of three values, say so, don’t hope.
  • Mark what’s required and set additionalProperties: false to keep the model from inventing extra keys.
  • Keep it focused. Deeply nested, sprawling schemas are harder for the model and easier to get subtly wrong.

Valid shape isn’t correct content

Structured outputs guarantee the form, that price is a number and status is one of your enums. They do not guarantee the value is right; the model can still extract the wrong number into a perfectly valid field. Validate business rules yourself; the schema handles structure, not truth.

FAQ

Is this the same as tool calling?

Closely related, a tool call’s arguments are a structured output (JSON matching the tool’s parameter schema). Structured outputs are the general mechanism; tool calling is one big use of it.

Does every model support it?

Most current major models support either JSON mode, schema-constrained outputs, or tool-based schemas, but the exact API and strictness differ by provider, so check the current docs for the model you’re using.

Will it stop hallucinations?

It removes format errors entirely. It doesn’t remove content errors, the model can still put a wrong but well-typed value in a field.

Related

Build schemas with the Structured Output Builder; see tool calling and AI Explained.