Structured outputs

Structured outputs ask a model to return JSON that follows a schema you define. Use them when the next step in your application needs fields, not a paragraph: a product record, a label, or a score.

The call uses the Responses API. Check that your model supports text.format with json_schema before relying on it.

Minimal example

This request extracts a product record. The schema requires a name, a list of features, a list of colors, and a price object.

import json
from openai import OpenAI

client = OpenAI()

description = """
Our Premium Laptop Backpack features padded compartments that fit
laptops up to 15.6 inches. Available in navy blue, black, and gray.
Price: $79.99, on sale for $64.99.
"""

response = client.responses.create(
    model="gpt-oss-120b",
    input=f"Extract structured product information: {description}",
    max_output_tokens=2000,
    text={
        "format": {
            "type": "json_schema",
            "name": "product_details",
            "schema": {
                "type": "object",
                "properties": {
                    "product_name": {"type": "string"},
                    "features": {"type": "array", "items": {"type": "string"}},
                    "colors": {"type": "array", "items": {"type": "string"}},
                    "pricing": {
                        "type": "object",
                        "properties": {
                            "regular_price": {"type": "number"},
                            "sale_price": {"type": "number"},
                            "currency": {"type": "string"},
                        },
                        "required": ["regular_price", "sale_price", "currency"],
                        "additionalProperties": False,
                    },
                },
                "required": ["product_name", "features", "colors", "pricing"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    },
)

print(json.dumps(json.loads(response.output_text), indent=2))

response.output_text is a JSON string. Example output from gpt-oss-120b (the wording of features varies from call to call):

{
  "product_name": "Premium Laptop Backpack",
  "features": ["Padded compartments", "Fits laptops up to 15.6 inches"],
  "colors": ["navy blue", "black", "gray"],
  "pricing": {
    "regular_price": 79.99,
    "sale_price": 64.99,
    "currency": "USD"
  }
}

Parameters

Set model, input, max_output_tokens, and text.format. Inside text.format, set type to json_schema, plus name, schema, and strict.

Chat completions accept the same schema as response_format={"type": "json_schema", "json_schema": {"name": ..., "schema": ..., "strict": True}}; the message content is then the JSON string. Both are confirmed on gpt-oss-120b.

Model support

The Responses API is confirmed for text, tool calls, and streaming on gpt-oss-120b. Some models return HTTP 400 for client.responses.create. Use Chat completions for those models.

Limitations

strict: True together with additionalProperties: false keeps the output to the fields in your schema. Validate the values in your code. For JSON arguments of a tool you defined, use Function calling.