Bottom line: At the time I’m writing this blog post, I could find no official documentation for the responses.parse() method. As best I can determine, responses.create() is a general purpose method that can do many things (including produce output in JSON format), and responses.parse() is a more specific method that is intended just to extract information in JSON format using a Pydantic library schema.

When using resposes.create() to extract or generate information in JSON format, you can use either 1.) formal JSON schema code, or 2.) detailed instructions and examples passed in the context. When using resposes.parse() to extract information in JSON format, you use a Pydantic class to define the desired output structure.

I put together a short demo that uses responses.create() with a formal JSON template, and uses responses.parse() with a Pydantic class. (The demo chess tournament information is artificial). Both calls generated identical JSON responses:

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 schema response is:
{ 
  "event_name":"Kashdan Memorial Chess Tournament",
  "event_date":"March 10, 2026"
}

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

So, the exact differences between responses.create() and respones.parse() can only be answered by comparing the parameters for the two methods. But I can’t do that until I can find the documentation for the responses.parse() method.

I captured the complete response from the raw JSON schema version (on the left) and the Pydantic schema version (on the right). The Pydantic version has parsed output, which might possibly be useful, but that information could be extracted from the output of the JSON schema version.

Notice that in both versions, the text field specifies type=’json_schema’. This suggests that behind the scenes, the Pydantic schema version is converted by responses.parse() to raw JSON schema. And this suggests that responses.parse() might be merely a wrapper that converts the easier-to-specify Pydantic schema to the trickier-to-specify raw JSON schema and then calls the responses.create() method. Maybe — I’m just speculating.

Out-of-date or non-existent documentation for newly emerging technologies is a common problem that I’ve had to deal with during my career. It is what it is.

Software development in situations with sparse documentation is like solving a mystery. I like old mystery movies that take place on a train. The limited amount of room that is available forces directors, writers, and actors to be clever and creative.

Right: The Lady Vanishes (1938) – Iris Henderson, a young tourist traveling on a train in Europe, makes acquaintance with an older woman, Miss Froy. The older woman disappears but nobody on the train except Iris remembers seeing her! With handsome fellow traveler Gilbert Redman, Iris unravels the mystery. It turns out that Miss Froy is a British secret agent who has been kidnapped and then hidden in plain sight as a bandaged patient of the villain, Dr. Hartz. Directed by Alfred Hitchcock. My grade = B.

Demo program:

# structured_output_pydantic.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,
}

response1 = 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 schema response is ")
print(response1.output_text)

from pydantic import BaseModel

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

response2 = client.responses.parse(
  model = "gpt-4o",
  input = [
    { "role": "system", "content": content_to_query },
    { "role": "user", "content": query },
  ],
  text_format = MyOutputSchema,
  max_output_tokens = 100,
  temperature = 0.2,
)

print("\nThe Pydantic version response is ")
print(response2.output_text)

print("\nEnd demo ")