Structured Output: Getting AI to Return JSON Your Systems Can Use

Plants.work · 2026-10-26 · upskilling

Understand JSON mode vs Structured Outputs, how to design a schema, and what to check before AI output flows into real systems.

You have AI read customer chats and write the details into a Google Sheet. The first hundred runs are fine. On run one hundred and one, the AI opens with "Sure! Here is the data you asked for" before the JSON, and the script waiting to parse it breaks. That is why AI tasks connected to real systems need structured output.

What is structured output?

Structured output means forcing the model to answer in a predefined structure, usually a JSON Schema that defines which fields exist, what type each field is and which fields are required. The result can go straight into code, a database or an automation tool without anyone trimming text by hand.

JSON mode vs Structured Outputs

Just asking in the prompt

Writing "reply in JSON only" works much of the time, but nothing guarantees it.

JSON mode

In its Structured Outputs announcement (August 2024), OpenAI explained that JSON mode produces valid JSON but "does not guarantee that the model's response will conform to a particular schema". Fields can go missing or be misnamed.

Strict Structured Outputs

You send a JSON Schema with the request, and constrained decoding forces every generated token to fit that structure. In the same announcement, OpenAI reported that on its complex JSON schema evals, gpt-4o-2024-08-06 with Structured Outputs scored 100%, versus under 40% for gpt-4-0613. Anthropic's Claude API also offers structured outputs, both for the response format and as strict tool use for tool calls, and Gemini offers a response schema too.

Designing a schema that works

Make as many fields required as possible: Claude's documentation recommends this to reduce complexity and control field order.
Use enums for limited options: for example, category = product, delivery, refund, other, so downstream systems never have to guess synonyms.
Write a description for each field: state meaning and units, such as price in baht without commas.
Give it a way out when data is missing: allow null or add a field like confidence instead of forcing the AI to guess.
Do not nest deeper than needed: flatter schemas are easier to check, and Claude's documentation notes schema complexity limits.

Example: triaging online shop messages

Prompt: "Read the following customer message and summarise it according to the given schema."

The schema has 4 fields: category (enum: product, delivery, refund, other), order_id (string or null), urgency (enum: low, medium, high) and summary (a short string, one sentence at most).

The message "I ordered a shirt on Monday, order number A1023, and still haven't received it" becomes category = delivery, order_id = A1023, urgency = medium, summary = customer has not received an item ordered on Monday. An automation can then route the case to the logistics team right away.

A correct structure does not mean correct data. A schema stops your system from breaking, not the AI from misunderstanding.

Things to watch out for

OpenAI itself notes that values can still be wrong even when the structure is right. Validate values in code, such as the order number format.
If a response is cut off by the max tokens limit or the model refuses, the output may not match the schema. Claude's documentation recommends checking stop_reason every time.
Not every JSON Schema feature is supported, and the first request with a new schema may be slower.
Personal data you extract must be stored in line with personal data protection law.

How to start

Pick a task where you currently copy AI output into another system by hand.
Write the schema from what the downstream system needs, not from what the AI happens to produce.
Turn on your provider's structured output mode instead of relying on the prompt alone.
Test with at least 30 real messages, including ambiguous ones and ones with missing data.

Structured output is the starting point for turning AI into a full workflow. Read the bigger picture in AI Workflow Automation, and if you want to build this skill systematically, browse related courses on Plants.work Learn.