Structured outputs

Structured Outputs ensures the model's reply matches your JSON Schema — set text.format.type (Responses) or response_format.type (Chat Completions) to "json_schema" and define your schema (name and schema).

For a yes/no, category, or rating judgment with probabilities, use the Decisions API instead.

Field reference

Note the Responses shape is flattened — name, strict, and schema sit directly on text.format — while Chat Completions nests them under response_format.json_schema. Both accept the same JSON Schema shape in schema.

Schema requirements

• Root type must be object.
• List every property in required.
• Set additionalProperties: false on each object.
• Supported types: string, number, boolean, integer, enum, array, nested object.

There is no native datetime type—use a string field with ISO 8601 in the name or description (for example, submit_by, detected_at).

For the full constraint list, see OpenAI's supported schemas.

Example

List Nobel Peace Prize winners from 2022 through 2024, classifying each as a person or an organization.

Shown below after parsing (same shape either way — only the output location differs, see Field reference):

{
  "laureates": [
    {
      "year": 2022,
      "name": "Ales Bialiatski",
      "kind": "👤",
      "country_code": "BY",
      "motivation": "Recognized for his tireless efforts to expose human rights abuses and promote democracy in Belarus."
    },
    {
      "year": 2022,
      "name": "Memorial",
      "kind": "🏛️",
      "country_code": "RU",
      "motivation": "Honored for its documentation of political repression and human rights violations in the Soviet Union and Russia."
    },
    {
      "year": 2022,
      "name": "Center for Civil Liberties",
      "kind": "🏛️",
      "country_code": "UA",
      "motivation": "Commended for its courageous work defending human rights and civil liberties in Ukraine."
    },
    {
      "year": 2023,
      "name": "Narges Mohammadi",
      "kind": "👤",
      "country_code": "IR",
      "motivation": "Awarded for her unwavering fight against oppression and her advocacy for women's rights in Iran."
    },
    {
      "year": 2024,
      "name": "Nihon Hidankyo",
      "kind": "🏛️",
      "country_code": "JP",
      "motivation": "Recognized for its efforts to achieve a world free of nuclear weapons and its work to eliminate nuclear weapons."
    }
  ]
}

Set stream to false or omit it for a single JSON response.

Response handling

Parse the JSON string at the output location from the field reference above. Before parsing, check for HTTP 4xx errors, refusals/incomplete status, and truncation, then validate the parsed JSON in your app.

Best practices

• Use the system message (or instructions) to interpret the schema. The schema sets shape; the system prompt sets meaning. Spell out formats, enums, and terse field names—the example above does this.
• Define fallbacks for missing data. Required fields still need a value when input omits them—e.g. "use 0 for exposure_usd when not applicable."
• Keep schemas small. Flat objects are easier to satisfy than deep nesting.

Related

• Responses API — structured output via text.format.
• Chat Completions API — request fields and response shape.
• Decisions API — yes/no, choice, and score judgments with probabilities.
• Function calling — tools and tool call outputs.
• Models — supported model IDs.
• OpenAI Structured Outputs — full feature reference.