OpenAI Structured Outputs: JSON Schema and Its Limits

Originally published August 8, 2024. Updated October 15, 2026.

Documentation review: this update checks OpenAI’s published announcement and developer documentation. GPTOnline did not run API tests. The JSON example below is illustrative.

OpenAI Structured Outputs lets developers specify the JSON structure an API response should follow. A correctly shaped result still needs a separate check for factual accuracy and suitability for the application.

Cover note: the retained 2024 image shows pink “STRUCTURED OUTPUTS” lettering on multicolored tiles. It is conceptual artwork, not an API screenshot or a test result.

The 2024 launch

OpenAI announced Structured Outputs on August 6, 2024. Its reported evaluation gave gpt-4o-2024-08-06 with Structured Outputs a 100% score for complex JSON schema following, compared with below 40% for gpt-4-0613. Those were OpenAI’s evaluation results for the stated task, not an independent GPTOnline benchmark or a guarantee that every answer would be true.

The announcement described constrained decoding: limiting which tokens can be generated according to the schema. It also acknowledged that values inside a valid object could still be wrong. That distinction matters when a result will update a record, display a claim or trigger an action.

Check model status today

The launch snapshot is historical. OpenAI’s deprecation notice dated October 14, 2026 lists gpt-4o-2024-08-06 for API shutdown on January 14, 2027, with gpt-6-luna as the recommended replacement. Deprecated does not mean already shut down.

For an implementation, confirm Structured Outputs support for your chosen model and endpoint in the current model documentation. A model name in a 2024 example should not become a permanent deployment choice.

Choose the right API path

Start with what the application needs to receive. Formatting a result for display and supplying arguments to a function are different integration tasks.

OpenAI’s Responses migration guide shows the endpoint-specific wrappers. Its function-calling guide explains strict tool arguments and endpoint-dependent defaults. Copying a response-format wrapper into the other endpoint is not a complete migration.

JSON mode is a separate option: it addresses JSON syntax, without enforcing your particular schema. The Chat Completions reference distinguishes json_object from json_schema.

Keep the schema small

The supported-schema rules cover a subset of JSON Schema. For a strict schema:

• Use an object at the root, without a root-level anyOf.
• List every property in required.
• Set additionalProperties: false on each object.
• Allow null when a required field may have no known value.

Unsupported constraints can cause a request error. Check restrictions for the selected model, including additional limitations for fine-tuned models.

An extraction example

Suppose a fictional warehouse note says: “Prepare three sample kits. The dispatch date will be confirmed later.” Your application needs a quantity and a date, while retaining the source text for review.

The following is an illustrative schema fragment for that data contract. It omits the endpoint wrapper, model selection and request handling; it is not runnable SDK code.

{
  "type": "object",
  "properties": {
    "kit_count": { "type": "integer" },
    "dispatch_date": { "type": ["string", "null"] },
    "source_text": { "type": "string" }
  },
  "required": ["kit_count", "dispatch_date", "source_text"],
  "additionalProperties": false
}

A hand-written example of the intended extraction is:

{
  "kit_count": 3,
  "dispatch_date": null,
  "source_text": "Prepare three sample kits. The dispatch date will be confirmed later."
}

Changing kit_count to 30 would still satisfy this schema’s integer requirement. The warehouse note is what establishes that the quantity should be three. Likewise, the schema permits a string in the date field; it does not establish that a dispatch date was actually supplied.

For this workflow, an application rule should preserve an unknown date as null, compare the extracted quantity with the source and check that the retained source text matches the input. A copied sentence is useful evidence for review, but the application must verify the copy.

Handle unsuccessful responses

A refusal or interrupted generation needs its own handling path. In Chat Completions, inspect the message’s refusal and the choice’s finish_reason. The API reference identifies length for a token-limit stop and content_filter for filtered content.

For Responses, check the response status and any incomplete_details, and recognize refusal content instead of assuming every message contains your expected JSON. OpenAI’s Structured Outputs examples demonstrate these branches.

In the warehouse example, keep an unsuccessful extraction out of the ready-to-dispatch queue. Preserve the original note and show an actionable review state. An empty object, a guessed quantity or an invented date would conceal the failure.

Check the whole workflow

A useful acceptance check asks more than whether JSON parsing succeeded. For the fictional extraction workflow, test these cases before relying on automated updates:

1. Clear input: the quantity matches the note and an explicitly supplied date is retained correctly.
2. Missing information: no date becomes null, rather than a plausible guess.
3. Conflicting information: a note that mentions two quantities goes to review under a defined business rule.
4. Unsuccessful generation: refusal, incomplete output and request errors do not create a dispatch record.
5. Repeat processing: a retry does not create a second record for the same note.

This is a proposed checklist, not a report of tests performed. OpenAI’s evaluation guidance recommends coverage of ordinary, edge and adversarial cases. Measure field accuracy and review rates alongside structural success so a formatting improvement cannot hide an extraction problem.

Formatting and customization

Structured Outputs addresses an output contract. Model customization is a separate decision. Our historical article on the GPT-4o fine-tuning launch covers that different topic; read its availability notes before using it as implementation guidance.

For a structured-data project, begin with a small contract, explicit failure handling and checks against the source. Expand the schema only when the consuming application has a clear use for the additional fields.