> ## 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 JSON mode or schema-shaped output in the Chat Completions compatibility layer.

`Chat Completions API` exposes structured outputs through `response_format`. Use this API when you need the OpenAI chat protocol rather than the newer `Responses` shape.

Use `json_schema` when the output must match a known shape. Use `json_object` when valid JSON is enough.

## Request

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

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

  completion = client.chat.completions.create(
      model="gpt-4.1",
      messages=[
          {
              "role": "user",
              "content": "Extract the event information.",
          }
      ],
      response_format={
          "type": "json_schema",
          "json_schema": {
              "name": "event",
              "schema": {
                  "type": "object",
                  "properties": {
                      "name": {"type": "string"},
                      "date": {"type": "string"},
                  },
                  "required": ["name", "date"],
                  "additionalProperties": False,
              },
              "strict": True,
          },
      },
  )

  print(completion.choices[0].message.content)
  ```

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

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

  const completion = await client.chat.completions.create({
    model: 'gpt-4.1',
    messages: [
      {
        role: 'user',
        content: 'Extract the event information.',
      },
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'event',
        schema: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            date: { type: 'string' },
          },
          required: ['name', 'date'],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4.1",
      "messages": [
        {
          "role": "user",
          "content": "Extract the event information."
        }
      ],
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "event",
          "schema": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "date": { "type": "string" }
            },
            "required": ["name", "date"],
            "additionalProperties": false
          },
          "strict": true
        }
      }
    }'
  ```
</CodeGroup>

## Wire Response Shape

Raw HTTP responses keep the result in `choices[0].message.content` as JSON text.

```json theme={null}
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"Science Fair\",\"date\":\"Friday\"}"
      },
      "finish_reason": "stop"
    }
  ]
}
```

## JSON Mode

If you only need valid JSON and not a full schema, use:

```json theme={null}
{
  "response_format": {
    "type": "json_object"
  }
}
```

## Which mode should you use?

| Mode          | Use it when                                  |
| ------------- | -------------------------------------------- |
| `json_schema` | required fields and schema validation matter |
| `json_object` | you only need valid JSON text                |

## Common mistakes

* expecting a native JSON object instead of parsing `choices[0].message.content`
* choosing Chat Completions for new work when Responses structured outputs would be the cleaner default
* using an open schema when downstream code expects strict shape guarantees

## Related Docs

* [Capability-level Structured Outputs](/build/structured-outputs)
* [Responses Structured Outputs](/api/responses/structured-outputs)
* [Create chat completion](/api-reference/endpoints/chat/completions)