> ## 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

> Compare schema-shaped output patterns across the supported generation APIs.

Structured outputs let you ask models for machine-readable results instead of unconstrained prose.

## JSON Prompting vs Schema Enforcement

Prompting for JSON only asks the model to behave. Schema enforcement gives the model an explicit shape to follow.

Use schema enforcement when your application depends on:

* required keys always being present
* enums staying valid
* arrays and nested objects staying well-formed
* downstream parsers not breaking on malformed text

## Support Matrix

| API                | Main request field                 | Notes                                                           |
| ------------------ | ---------------------------------- | --------------------------------------------------------------- |
| `Responses`        | `text.format`                      | Best starting point for new structured-output work              |
| `Chat Completions` | `response_format`                  | Use when you need OpenAI chat compatibility                     |
| `Messages`         | No generic structured-output field | Use tool schemas for Anthropic-style tool workflows when needed |

## When To Use It

* extract entities, events, or records into a fixed schema
* feed model output into downstream automation
* reduce parser failures caused by malformed JSON

## Recommended Example

<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 the event details from: Alice and Bob are going to a science fair on Friday.",
      text={
          "format": {
              "type": "json_schema",
              "name": "calendar_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 the event details from: Alice and Bob are going to a science fair on Friday.',
    text: {
      format: {
        type: 'json_schema',
        name: 'calendar_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 the event details from: Alice and Bob are going to a science fair on Friday.",
      "text": {
        "format": {
          "type": "json_schema",
          "name": "calendar_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>

Raw HTTP responses still carry the structured result as JSON text inside the normal output content. Exact wire examples live in the API-specific guides.

## API-Specific Guides

* [Responses Structured Outputs](/api/responses/structured-outputs)
* [Chat Completions Structured Outputs](/api/chat-completions/structured-outputs)

## Pitfalls

* JSON prompting is weaker than schema enforcement
* `strict: true` helps, but your schema still needs `required` fields and closed objects where that matters