OpenAI Structured Outputs Guide: How to Get GPT to Return Schema-Valid JSON

Once model output hits a database, a form, or a downstream Agent, “please return JSON” in the prompt is not a contract. OpenAI Structured Outputs uses constrained decoding to pin the reply to your JSON Schema: keys stay present, enums stay in the set, types do not drift between string and number. This guide is for engineers doing extraction, ticket classification, eval scoring, and multi-step workflows — the path from JSON Mode to strict: true.

Why JSON Mode is not enough

JSON Mode (type: "json_object") only guarantees that a JSON parser can read the payload. It does not lock key names, required fields, enum sets, or numeric types. The three production failures we see most: missing severity, 42 written as "42", and an invented urgent-plus outside the enum. Strong typing downstream then fails on random samples.

OpenAI treats Structured Outputs as the successor to JSON Mode: new work should start from a Schema, not from three retries after parse failure. If you are also comparing token bills across models, see Kimi K3 vs GPT-5.5 API cost — structured output barely grows payload size; retries and long reasoning are what move the invoice.

Minimal working request

This ticket-extraction Schema covers most production needs: string, enum, integer, and a null union for optional fields. The model must return every key; if there is no account ID, emit null instead of dropping the key.

{
  "model": "gpt-4o-2024-08-06",
  "messages": [
    {"role": "system", "content": "Extract the user description into a support ticket object."},
    {"role": "user", "content": "Checkout page returns 500 when using a saved card. Started today. Account acct_8842."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "category": {
            "type": "string",
            "enum": ["billing", "bug", "account", "other"]
          },
          "severity": { "type": "integer" },
          "account_id": { "type": ["string", "null"] }
        },
        "required": ["summary", "category", "severity", "account_id"],
        "additionalProperties": false
      }
    }
  }
}

On the Responses API, place the same Schema under text.format, with type, name, schema, and strict as siblings. The first request for a Schema compiles constraints and may be a bit slower; that Schema is then cached and later calls return to normal latency.

Rules a strict Schema must satisfy

With strict: true, you are no longer sending “loose JSON Schema.” You are sending the supported subset. Violations return 400 — not “best effort.”

• Root must be object: the root cannot be anyOf or an array. If Zod’s discriminatedUnion emits a top-level anyOf, wrap it, e.g. { "result": ... }.
• Every object needs additionalProperties: false: nested objects included. Miss one and the request is rejected.
• Every key in properties must appear in required: optional meaning uses "type": ["string", "null"] or anyOf plus null.
• Supported types: string, number, integer, boolean, object, array, enum, anyOf.
• String constraints: pattern, format (email, date-time, uuid, ipv4, and similar).
• Numbers and arrays: minimum / maximum / multipleOf; minItems / maxItems.
• Explicitly unsupported: allOf, not, if/then/else, dependentRequired, and other combinators.
• Size limits: about 5000 object properties total, 10 nesting levels; combined length of property names, definition names, and enum strings ≤ 120,000 characters; at most 1000 enum values.

Tool calls vs message body

The same strict rules apply to function / tool parameters. The intent differs: a tool Schema describes “what the model should call”; response_format / text.format describe “what shape the model should reply with.” Use the latter for extraction, scoring, and UI state; use the former for weather, file writes, and commands. If you are comparing terminal agents with GUI control, see how Claude Code relates to OpenAI Computer Use — that is the “how to act” layer; this article is the data contract before and after the action.

Parse straight into objects with the SDK

Hand-written JSON Schema often drops required. Official SDKs ship Pydantic / Zod helpers: generate the Schema from types, and get a parsed object on the response. Typical Python:

from typing import Literal, Optional
from pydantic import BaseModel
from openai import OpenAI

class SupportTicket(BaseModel):
    summary: str
    category: Literal["billing", "bug", "account", "other"]
    severity: int
    account_id: Optional[str]

client = OpenAI()
completion = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "Extract a support ticket."},
        {"role": "user", "content": "Checkout page 500, account acct_8842."},
    ],
    response_format=SupportTicket,
)
ticket = completion.choices[0].message.parsed
if completion.choices[0].message.refusal:
    raise RuntimeError(completion.choices[0].message.refusal)
print(ticket.category, ticket.severity)

Errors, refusals, and a ship checklist

Run this list before production. It kills most “curl works locally, pipeline returns 400” incidents.

• 400 Unsupported schema: missing additionalProperties: false, a property not in required, root anyOf, or use of allOf.
• Model refusal: when safety policy fires, content is not stuffed into the Schema. Read refusal, show it in the UI, and do not retry as a JSON parse failure.
• Optional fields become empty strings: if the contract says null, accept null. Map to SQL NULL before insert; do not guess again.
• Enums too wide: keep business states to 5–8 values. Hundreds of enums burn context and approach the 1000-value cap.
• Key order: output keys follow Schema declaration order, so streaming clients can parse field by field.
• Prompts still matter: Schema owns shape; the prompt owns meaning. “severity 1–5, 5 is a site-wide outage” belongs in system; lock the integer range again with minimum / maximum.

Ship three habits: Schema in Git; separate metrics for refusal, 400, and timeout; a regression set of real tickets, not “Hello, return JSON.” Once parsing is stable, you can spend time on classification accuracy and latency instead of weekly regex patches.