How to beginner · 3 min read

OpenAI structured outputs supported types

Q: OpenAI structured outputs supported types

OpenAI structured_outputs supports types including object, array, string, number, boolean, and null. These types enable you to define precise JSON schemas for reliable, machine-readable responses from models like gpt-4o.

Quick answer

OpenAI structured_outputs supports types including object, array, string, number, boolean, and null. These types enable you to define precise JSON schemas for reliable, machine-readable responses from models like gpt-4o.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

Install SDK: pip install openai
Set environment variable: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install openai

Step by step

Use the response_format parameter in your chat.completions.create call to specify the expected JSON schema with supported types.

Supported types include:

object - JSON objects with defined properties
array - Lists of items of a specified type
string - Text values
number - Numeric values (integer or float)
boolean - True or false values
null - Null values

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "is_student": {"type": "boolean"},
        "courses": {
            "type": "array",
            "items": {"type": "string"}
        }
    },
    "required": ["name", "age", "is_student"]
}

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Provide a JSON with name, age, is_student, and courses."}],
    response_format={"type": "json_schema", "json_schema": schema}
)

print(response.choices[0].message.content)

output

{
  "name": "Alice",
  "age": 23,
  "is_student": true,
  "courses": ["Math", "Physics"]
}

Common variations

You can define nested object types, use null for optional fields, and combine types with anyOf or oneOf. Models like gpt-4o and gpt-4o-mini support structured outputs.

Example variations include:

Arrays of objects
Optional fields with nullable: true
Enumerations with enum

python

nested_schema = {
    "type": "object",
    "properties": {
        "user": {
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "email": {"type": ["string", "null"]}
            },
            "required": ["id"]
        },
        "tags": {
            "type": "array",
            "items": {"type": "string"}
        }
    },
    "required": ["user"]
}

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Generate user info with optional email and tags."}],
    response_format={"type": "json_schema", "json_schema": nested_schema}
)

print(response.choices[0].message.content)

output

{
  "user": {
    "id": "u123",
    "email": null
  },
  "tags": ["beta", "tester"]
}

Troubleshooting

If the model returns unstructured or invalid JSON, verify your schema is valid JSON Schema and that the model supports response_format. Use max_tokens sufficiently large to fit the output. If parsing errors occur, consider adding content-type: application/json in your prompt or system instructions.

✅

Key Takeaways

Use response_format with JSON Schema types: object, array, string, number, boolean, null.
Define precise schemas to get reliable, machine-readable JSON from gpt-4o and similar models.
Nested objects and arrays are fully supported for complex data structures.
Validate your schema and increase max_tokens to avoid truncated or malformed outputs.
Use nullable or anyOf to handle optional or multiple types.

Verified 2026-04 · gpt-4o, gpt-4o-mini

Verify ↗