Structured Outputs (JSON) and Why They Matter for Design

A structured output is a model response in JSON with a fixed schema. What Anthropic, OpenAI and Google guarantee, what they do not, and how to design for it.

info Quick Definition

A structured output is a model response in a fixed, predictable format, usually JSON with defined fields, that the application can read and validate without interpreting free text. It is what lets a model connect to interface components, databases and other systems.

What is JSON, and why does it appear here?

JSON (JavaScript Object Notation) is a text format for storing and sending data as key-value pairs and lists. Its values are double-quoted strings, numbers, true, false, null, lists in square brackets or objects in curly braces. It has no comments and no trailing commas. Although it was born alongside JavaScript, almost any language can read and write it.

A model that answers in free text, such as “Sure, here is the answer: …”, is hard to process. A model that answers with {"title": "...", "priority": "high"} can feed a form directly. The difference is not the model’s intelligence but what the application can do with its output.

How is it achieved?

There are three levels, from least to most guaranteed:

Asking in the prompt. Describing the format and giving an example. It is the simplest and least reliable way.
Using the provider’s structured-output feature, when available, which constrains generation to a defined schema (constrained decoding).
Validating afterwards. Checking the response against a schema, for example with JSON Schema, which describes fields, types, required items and allowed values. If it fails, retry or show an error state.

It is best to combine levels: ask for the format, use the provider’s feature if available, and always validate before using the data.

What do Anthropic, OpenAI and Google offer today?

All three providers let you pass a JSON schema and force the response to follow it. Parameter names change and documentation moves, so check it before implementing.

Provider	How you ask	What it guarantees	What it does not
Anthropic (Claude)	`output_config.format` with `type: "json_schema"` and a `schema`; for tools, `strict: true` on the definition	Valid JSON matching the schema, with required fields and correct types	Does not support numeric or length constraints in the schema (`minimum`, `maxLength`) and rejects them with a 400 error; on a refusal (`stop_reason: "refusal"`) or a `max_tokens` cut-off, the output may not match
OpenAI	`text.format` with `type: "json_schema"`, `name`, `schema` and `strict: true` (Responses API); `response_format` in Chat Completions	The response follows the schema; refusals arrive in a `refusal` field	Every property must be in `required` and every object needs `additionalProperties: false`; a response cut by `max_output_tokens` is incomplete
Google (Gemini)	`response_format` with `mime_type: "application/json"` and `schema` (Interactions API documentation)	Syntactically valid JSON that fits the schema	Silently ignores keywords such as `minLength` or `maxLength`; values must be validated in the application

The common lesson: the schema guarantees shape, not truth. A severity field will always be “low”, “medium” or “high”, but the model can pick the wrong one. That is why validation and an interface error state are still needed.

Here is a minimal schema for the example below, compatible with those restrictions (all fields required and additionalProperties: false):

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "severity": { "type": "string", "enum": ["low", "medium", "high"] },
    "screen": { "type": ["string", "null"] }
  },
  "required": ["title", "severity", "screen"],
  "additionalProperties": false
}

And a valid response:

{ "title": "The Save button does nothing", "severity": "high", "screen": null }

Why does this matter to a designer?

Because the interface depends on predictable data:

Components that do not break. If the model renames a field or returns a number as text, a card or chart can fail or show a wrong value.
Designed error states. If validation fails, the user needs something useful: “I couldn’t extract the date, would you enter it?” is better than an empty screen.
Human editing. A form pre-filled with structured output lets users correct field by field, which is very hard with free text.
Visual consistency. A fixed format lets you design reusable components for AI results.

When NOT to use it?

When the answer is text to read, such as an email or a narrative summary. Forcing it into JSON impoverishes the result and adds complexity. Nor is it wise when the schema changes constantly: every change requires updating validations, components and tests.

Comparison: free text or structure

Criterion	Free text	Structured output
Human reading	Excellent	Fair, unless there is a preview
Integration with components	Hard: must be interpreted	Direct, field by field
Error handling	Vague: “I found nothing”	Explicit: empty or invalid field
Risk of broken format	Not applicable	Exists; must be validated
Best for	Summaries, emails, explanations	Forms, cards, tables, flows

A practical flow

Define the result schema with fields, types and allowed values.
Write the prompt with the schema and one valid example.
Validate every response before showing it.
If it fails, retry once; if it fails again, show an error state with a clear action.
Log the failures to review which fields are hard to extract.

Example

Illustrative example: an app turns screenshots of support tickets into design tasks using the schema above. Because the schema fixes the three severities, the card never receives a color that does not exist. Still, the model labels as “high” a ticket that only asks to change the shade of a grey. The interface shows severity in an editable field tagged “Suggested by AI”, and the reviewer fixes it with one click. If the team relied on the prompt alone, without the provider feature, it would also need to validate that severity is one of the three values and show an error state when “very high” arrives. The designer gains two things: an explicit error state and a field that makes clear the value is a proposal.

Common mistakes

Trusting that the model will always return valid JSON without validating.
Designing components for the happy path and forgetting empty or invalid fields.
Mixing free text with JSON in the same response.
Changing the schema without versioning it or updating the interface.
Using structured output for tasks that read better as text.

Sources

JSON, Wikipedia
JSON Schema, Wikipedia
Anthropic, “Structured outputs”: https://platform.claude.com/docs/en/build-with-claude/structured-outputs
OpenAI, “Structured Outputs”: https://developers.openai.com/api/docs/guides/structured-outputs
Google, “Structured output” (Gemini, Interactions API): https://aistudio.google.com/docs/structured-output

Frequently asked questions

What is a structured output?

It is a model response that follows a fixed, predictable format, such as JSON with defined fields, so an application can process it reliably.

Why is asking for JSON in the prompt not enough?

Because the model can drop a comma, add text before the JSON or invent a field. Asking helps, but it does not guarantee the format. Validate every response.

What is JSON Schema?

It is a format for describing the structure JSON data must have: fields, types, required items and allowed values. It is used to validate a response before using it.

Does a structured output guarantee the data is correct?

No. With the provider feature the response follows the schema (fields, types, allowed values), but the content can still be wrong, or cut short by a refusal or the token limit. Validate it and design the error state.

Why does a designer care?

Because the interface depends on predictable data. If the model renames a field or changes its type, a component can break or show wrong information.