> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Outputs

> Use schema-shaped output with the Responses API.

Use `text.format` when your application needs schema-shaped output instead of free-form prose. On the wire, the structured result still comes back as JSON text inside a normal `message` item.

Choose this when downstream code depends on a predictable schema, not just "please answer in JSON" prompting.

## Request

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.naga.ac/v1",
      api_key="YOUR_API_KEY",
  )

  response = client.responses.create(
      model="gpt-4.1",
      input="Extract an event from: Alice and Bob are going to a science fair on Friday.",
      text={
          "format": {
              "type": "json_schema",
              "name": "event",
              "schema": {
                  "type": "object",
                  "properties": {
                      "name": {"type": "string"},
                      "date": {"type": "string"},
                      "participants": {
                          "type": "array",
                          "items": {"type": "string"},
                      },
                  },
                  "required": ["name", "date", "participants"],
                  "additionalProperties": False,
              },
              "strict": True,
          }
      },
  )

  print(response.output_text)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.naga.ac/v1',
    apiKey: 'YOUR_API_KEY',
  });

  const response = await client.responses.create({
    model: 'gpt-4.1',
    input: 'Extract an event from: Alice and Bob are going to a science fair on Friday.',
    text: {
      format: {
        type: 'json_schema',
        name: 'event',
        schema: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            date: { type: 'string' },
            participants: {
              type: 'array',
              items: { type: 'string' },
            },
          },
          required: ['name', 'date', 'participants'],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4.1",
      "input": "Extract an event from: Alice and Bob are going to a science fair on Friday.",
      "text": {
        "format": {
          "type": "json_schema",
          "name": "event",
          "schema": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "date": { "type": "string" },
              "participants": {
                "type": "array",
                "items": { "type": "string" }
              }
            },
            "required": ["name", "date", "participants"],
            "additionalProperties": false
          },
          "strict": true
        }
      }
    }'
  ```
</CodeGroup>

## Response Shape

```json theme={null}
{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "{\"name\":\"Science Fair\",\"date\":\"Friday\",\"participants\":[\"Alice\",\"Bob\"]}",
      "annotations": [],
      "logprobs": []
    }
  ]
}
```

## Choose the right mode

| Mode          | Use it when                                                           |
| ------------- | --------------------------------------------------------------------- |
| `json_schema` | you need required fields, enums, nested objects, or strict validation |
| `json_object` | you only need valid JSON without full schema enforcement              |

## How To Read The Result

* parse the JSON string from `output[*].content[*].text`
* if you only need valid JSON and not schema enforcement, use `text.format.type: "json_object"` instead

## Caveats

* `strict: true` works best with a closed schema such as `additionalProperties: false`
* the wire response remains item-based even when the output is structured
* model support still depends on the selected model

## Common mistakes

* expecting a native JSON object instead of parsing the returned text
* using an open schema when the app really needs closed, validated output
* assuming every model supports strict schema following equally well

## Related Docs

* [Capability-level Structured Outputs](/build/structured-outputs)
* [Responses API](/api/responses)
* [Create response reference](/api-reference/endpoints/responses/create)