Responses API documentation on structured outputs is lacking

[stur86]

I’ve been trying to use directly the Responses API (for batch querying) to produce structured outputs, but have run in quite a few difficulties. The old response_format key is deprecated, now we have to use text, but it’s unclear how to do so. I ended up understanding that the correct way should be:

"text": {
    "format": {
         "type": "json_schema",
         "schema": <insert your JSON schema here>
    }
}

but this was far from obvious, it was not explained in the Structured Output docs (which takes a higher level view of using the relevant libraries for this) and I only worked it out in the end by looking into the source code of the Python openai library. Could it be made maybe a more clear?

EDIT: turns out it’s even more complicated because the JSON schema has to be strict. I ended up using just

from openai.lib._parsing._responses import (
    type_to_text_format_param
)

to create the object. If to get something this basic working you need to import two underscore prefixed modules something is wrong.

[aprendendo.next]

Hi, welcome to the forum and thanks for sharing your findings.

Another alternative is to use with_raw_responses to watch the payload for any given request, then use it as a model for configuring your batch files:

from pydantic import Field,BaseModel

class FormattedResponse(BaseModel):
    answer:str = Field(description='The usual prompt response')
    alternative_answer:str = Field(description='What else did you consider')

text = "What color is the sky?"

response = client.responses.with_raw_response.parse(
    model="gpt-4.1-mini",
    input=text,
    text_format=FormattedResponse,  # Pydantic BaseModel as schema input
)

print(response.parse().output_parsed)
print("payload",response.http_request.content.decode('utf-8'))

[Jemmery]

I gave up and stuck with chat completions for much the same reason. I just could not work out how to get the json schema setup right for the responses api. The documentation looks good but then transpires to just be lacking in necessary detail in so many places!

[_j]

See if this helps. I developed what is actually needed to give that “aha” moment of understanding.

TIP: API creation of structured (strict) output - documentation improved a bit, with helper code

From other code, I pulled out and made a Python function to address a knowledge and documentation shortcoming, and code itself is readable as documentation. Or you can just use the function. Builds the correct structured response output format for JSON schema for either: the Responses API text container (for the request’s text parameter), or the Chat Completions response_format container, using for_chat_completions=True, You can get a strict structured output parameter to use with only: yo…

[John_Doe5]

Agreed with the others. The documentation is lacking in this area. IMO there should be one example for the legacy chat completions API and one example for the new responses API.

The Responses API subsection provides a link to the Structured outputs page, which uses examples that adapt to the legacy chat completions API. As you could imagine, this knowledge discontinuity makes it difficult for us to develop around the new Responses API

[John_Doe5]

I did some detective work and I found that the following works for me:

{
  "input": "<some-prompt>",
  "model": "<some-model>",
  ...
  "text": {
    "format": {
      "name": "<choose-a-name>",
      "schema": {
        "additionalProperties": false,
        "properties": {
          "<result_1>": {
            "type": "string"
          },
          "<result_2>": {
            "type": "string"
          }
        },
        "required": [
          "<result_1>",
          "<result_2>"
        ],
        "type": "object"
      },
      "strict": true,
      "type": "json_schema"
    }
  }
}

This still needs to be formally documented somewhere though. I am using libcurl to interact with the API so I needed to know the exact structure of the data JSON. BTW it also appears there are several doc bugs. For example, the documentation, here, does not make any mention of the name item. But the API returns the error message: Missing required parameter: 'text.format.name' if name is not supplied in the format object.

As a corollary, name is apparently required under the schema object (see here) but when I deploy my example JSON without the name key, I get a 200 response so…

[_j]

@John_Doe5

This still needs to be formally documented somewhere though.

I offer a function that can take the primitives, a schema and the “container metadata”, a parameter whether it is for_chat_completions, and delivers your API call’s “text” for Responses or “response_format” for Chat Completions:

@_j

From other code, I pulled out and made a Python function to address a knowledge and documentation shortcoming, and code itself is readable as documentation.

Or you can just use the function. Builds the correct structured response output format for JSON schema for either:

• the Responses API text container (for the request’s text parameter), or
• the Chat Completions response_format container, using for_chat_completions=True,

Run the full python script and it even runs the same schema against both endpoints as “proof”.

So, I gave that forum topic a title including, “documentation improved a bit”

[John_Doe5]

Great! Thanks for the speedy update