OpenAI Enforces Exact JSON Responses with Structured Outputs

On August 6, 2024, OpenAI introduced Structured Outputs so an API response could be required to match a declared JSON schema. The announcement and technical guide documents compatible models, modes, evaluations and limits: the feature controls output shape but does not guarantee that its values are true.

The feature is available on the GPT-4o-2024-08-06 and GPT-4o mini-2024-07-18 models. According to OpenAI, its internal tests put GPT-4o with Structured Outputs at 100% compliance with complex schemas, compared with less than 40% for GPT-4-0613 using earlier methods. Primary source.

From valid JSON to usable JSON

JSON is a widely used text format for exchanging data between programs. A retailer, for example, might need a model to extract a product name, category, maximum price and list of filters from a query. It is not enough for the model to respond in JSON: it must use exactly those fields, with the expected data types and without inventing additional ones.

Until now, developers could ask for a JSON response or describe the format in the message sent to the model. That reduced errors but did not eliminate them. The model could omit a required field, return a number as text or add an explanation before the JSON object. Any of those failures requires validation, retries and additional rules in the software receiving the response.

Structured Outputs lets developers define a schema using JSON Schema, a specification that describes which data is admissible: required fields, possible values, nested objects or lists. For compatible schemas and requests that are not refused, the API aims to make the response conform to that definition when the strict: true option is enabled.

Two ways to use the feature

OpenAI has integrated this capability into two parts of its API. The first is function calling, or tools: the developer describes an action the model can request, such as checking a catalog, booking an appointment or looking up an order. In strict mode, the arguments for that call must follow the declared schema.

The second is the response format. Instead of simply asking for JSON, an application can send a schema using the json_schema format and receive output ready to be processed by code.

This does not mean the model suddenly knows data it did not know before, nor that it stops making reasoning errors. It guarantees the form of the response, not the truth of its content. If asked to classify a complaint or extract data from an ambiguous document, it can still misinterpret the text; the difference is that it will deliver that interpretation in a predictable structure.

Less integration work

The improvement is especially valuable in use cases where the model is one component in a larger process rather than an isolated chatbot. It can turn invoices into records, convert conversations into forms, extract information from contracts, generate interfaces from instructions or feed customer service systems.

It also narrows the gap between a prototype and a product. A developer can put together a demo with free-form responses in minutes, but deploying it requires handling exceptions: missing fields, invalid formats and outputs that break an automation. Enforcing the schema does not replace business checks — such as verifying that an amount actually exists in a database — but it removes a common class of formatting failures.

OpenAI supports JSON Schema within a subset of the specification, a reasonable restriction that allows the system to guarantee compliance. The documentation also covers safety refusals: if the model refuses a request, the application can distinguish that refusal from a normal structured response.

The feature comes with no specific additional charge: it uses the pricing for compatible models. GPT-4o costs $5 per million input tokens and $15 per million output tokens; GPT-4o mini costs 15 cents and 60 cents, respectively. Primary source.

The move shows where a less visible part of the competition between models is taking place: not just in answering a question better, but in behaving predictably enough to integrate into real-world software. For companies, that formatting reliability may matter more than a marginal improvement in conversational quality.

There are three kinds of validity

An output can be valid JSON while violating the schema; it can match the schema while containing an impossible fact; it can pass both layers while breaking a business rule. Structured Outputs acts at the second boundary. The application still needs semantic validation, permissions, a query to the real database and confirmation before an irreversible action.

A numeric price field prevents a sentence but not a fabricated amount. An enumeration limits possible labels but does not prove the classification is correct. A schema reduces unexpected states; it does not turn a prediction into a record of truth.

Design a schema that can fail well

Required fields should genuinely be obtainable. When a document may omit a value, represent absence explicitly instead of forcing the model to complete it. Separate “not found”, “ambiguous” and “refused for safety” because each state leads to a different action.

Tests should include empty, contradictory, huge, multilingual and hostile inputs. Check that a refusal is not interpreted as normal data and that a length cutoff is not accepted as a complete object. Record every error with schema, model and version; blind retries can multiply cost without correcting the cause.

The contract serves both sides

The consuming team defines meaning, units and examples while the model-calling team versions the schema. Adding a field or changing an enumeration is tested like any API change. An automatically generated interface should not hide unknown values or execute by default.

Useful metrics separate structural compliance, field accuracy, coverage and human-review rate. Celebrating only that the parser stopped failing may hide a quality decline. A labelled sample and results by document type reveal where the system needs another source or a manual path.

In production, retain the received object before transformation when data policy permits. That makes an error reproducible and separates failures born in the model, validation or a later mapping. Logs remove secrets and have defined retention; observability does not mean collecting sensitive content forever.

Deployment also needs a compatibility path. If a new model interprets the same description differently, contract tests should catch it before migration. Versioning prompt, schema and model together allows a return to a known combination without mixing causes.

A complete boundary example

For an invoice, the schema may require supplier, currency and line items while allowing a null tax number. The model extracts candidates; a rule sums amounts and queries the supplier master; a person reviews any mismatch. No layer pretends to do the others’ work, and every rejection leaves an actionable reason.

If the document contains two currencies or a handwritten note, the output declares ambiguity instead of choosing. That design decision often adds more reliability than making every field strict: automation can process clear cases and route uncertain ones to the right queue.

The transferable skill is to place the model inside a verifiable contract: schema for shape, rules for meaning and external authority for action. With those three layers, Structured Outputs removes brittle glue without asking format to guarantee truth.