I was working on a problem using the OpenAI system and I needed the output to be in JSON format rather than the usual free-form text. Producing JSON output can be accomplished by feeding a JSON schema to the responses.create() method.

I set up some simple text to query about a hypothetical upcoming chess tournament and asked GPT to give me the event name and date, in JSON format. The output of my demo is:

Begin OpenAI structured JSON output demo

The content to query is:

The Kashdan Memorial Chess Tournament will be played in
Venice, Italy on March 10, 2026. There will be nine
players. Participants will likely include Fabiano Caruana
(USA) and Anish Giri (Netherlands).

The query is:
Extract the event information

The JSON response is:
{
  "event_name":"Kashdan Memorial Chess Tournament",
  "event_date":"March 10, 2026"
}

End demo

The key is specifying a JSON schema:

my_output_schema = {
  "type": "object",
  "properties": {
    "event_name": { "type": "string" },
    "event_date": { "type": "string" },
  },
  "required": [ "event_name", "event_date" ],
  "additionalProperties": False,
}

For this simple example, I was able to craft the schema directly, by hand. But in a non-demo scenario, creating a JSON schema can be very difficult, and I usually rely on a tool that accepts an example of JSON data and then infers a schema for you. The online tool at liquid-technologies.com/online-json-to-schema-converter is an example.

Another technique to generate JSON schema is to use the popular Pydantic library, where you define something similar to a Python class and then call the schema() or model_json_schema() method (depending on the version of Pydantic you’re using). For example:

from pydantic import BaseModel

class MyOutputSchema(BaseModel):
  event_name: str
  event_date: str

my_schema = MyOutputSchema.schema()  # v1
# my_schema = MyOutputSchema.model_json_schema()  # v2

When using the Responses API, an alternative to using a JSON schema is to provide detailed instructions to the input, either in the query, or in the “instructions” parameter. Using JSON schema is more difficult, but is usually (but not always) more reliable.

One of my chess heros, when I was a serious chess player, was Grandmaster Isaac Kashdan. Kashdan was the driving force for chess in Southern California in the 1950s through the 1970s, and a gracious, intelligent man. Kashdan was clearly one of the top three players in the world for several years, but he never got a chance to play in a world championship match.

Right: Kashdan (on the right) playing World Champion Alexander Alekhine in a casual game in 1932.

Demo program:

# structured_output_json_schema.py

from openai import OpenAI

print("\nBegin OpenAI structured JSON output demo ")

key = "sk-proj-_AX7bGTXUwg-qojh2T5Z2CVXrox" + \
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + \
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + \
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

client = OpenAI(api_key=key)

content_to_query = "The Kashdan Memorial Chess " + \
  "Tournament will be played in Venice, Italy " + \
  "on March 10, 2026. There will be nine " + \
  "players. Participants will likely include " + \
  "Fabiano Caruana (USA) and Anish Giri (Netherlands)."
print("\nThe content to query is: ")
print(content_to_query)

query = "Extract the event information"
print("\nThe query is: ")
print(query)

my_output_schema = {
  "type": "object",
  "properties": {
    "event_name": { "type": "string" },
    "event_date": { "type": "string" },
  },
  "required": [ "event_name", "event_date" ],
  "additionalProperties": False,
}

response = client.responses.create(
  model = "gpt-4o",
  input = [
    { "role": "system", "content": content_to_query },
    { "role": "user", "content": query },
  ],
  text = {
    "format": {
      "type": "json_schema",
      "name": "demo",
      "schema": my_output_schema,
      "strict": True,
    },
  },
  max_output_tokens = 100,
  temperature = 0.2,
)

print("\nThe JSON response is ")
print(response.output_text)

print("\nEnd demo ")