OpenAI Structured Outputs

Structured Outputs lets you enforce a JSON output with an optional schema to your model generation.

Structured Outputs are ways for models to respond using JSON formatting, either by building objects dynamically or following a given JSON Schema.

Prerequisites

Structured Outputs are only available when using the following models:

  • gpt-4o 2024-08-06 and later
  • gpt-4o-mini 2024-07-18 and later

Why using Structured Outputs

  • Reliable format: You don’t have to check or fix responses using the wrong format anymore.
  • Clear refusals: When the model refuses something for safety reasons, it’s now easily detectable programmatically.
  • Easier prompts: You don’t need to prompt the model to adhere to the schema anymore.
    Using Structured Outputs

Types of Structured Outputs

There are two types of Structured Outputs:

  • JSON Mode - A simpler version of the Structured Outputs feature that ensures the output is always a valid JSON format.
  • JSON Schema (recommended) - This option not only ensures the JSON is valid but also guarantees it adheres to the specified schema.

Adding a response format to a model configuration

When configuring a model in Playgrounds or Deployments using compatible models, you can decide on the response format for your model generation using the Response Format button.

By default, the Response Format is None, outputting a regular text queried by the user.


JSON Mode

The next option for Response Format is JSON mode.

JSON mode will dynamically generate a structurally valid JSON following your query.

Here by asking a list of 5 cities we're receiving a valid JSON array containing 5 examples.

Here by asking a list of 5 cities we're receiving a valid JSON array containing 5 examples.

🚧

To activate JSON mode, you specifically need to mention this in your system or user promt.

JSON Schema

By choosing JSON Schema for your Response Format, you can enforce a given Schema to your query, making sure that the response will match the expected output.

Following the previous example, I choose to add the following schema using the Schema button for the cities I am listing:

{
  "name": "cities",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "cities": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "name",
            "country"
          ]
        }
      }
    },
    "additionalProperties": false,
    "required": [
      "cities"
    ]
  }
}

By then querying again the model, the output is changed and is now matching the previously defined JSON Schema.

Here the model generates following the previously defined JSON Schema.

Here the model generates following the previously defined JSON Schema.


Adding Structured Outputs to a Tool

Another method of utilizing Structured Outputs is through a Tool.

Enabling Structured Outputs through the Tool setup.

Enabling Structured Outputs through the Tool setup.