Structured output

Structured output helps you use model responses directly in software. Instead of asking for free-form text and parsing it later, you can request JSON or a strict JSON Schema shape. Use it for extraction, form filling, configuration generation, routing decisions, and any workflow where downstream code expects stable fields.

JSON mode

JSON mode asks the model to return valid JSON:

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You extract information and return JSON only."},
    {"role": "user", "content": "Alice is 28 and works as an engineer. Extract name, age, and job."}
  ],
  "response_format": {
    "type": "json_object"
  }
}

JSON mode guarantees valid JSON, but it does not guarantee a specific field structure. Describe the expected keys clearly in the prompt when you use this mode.

JSON Schema mode

Use json_schema when you need a stricter shape:

{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "Alice is 28 and works as an engineer."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "job": {"type": "string"}
        },
        "required": ["name", "age", "job"],
        "additionalProperties": false
      }
    }
  }
}

Important fields:

strict: true asks the model to follow the schema closely.
required lists fields that must be present.
additionalProperties: false prevents unexpected fields.

Python example

import json
from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://moxus.ai/v1")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Alice is 28 and works as an engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "job": {"type": "string"},
                },
                "required": ["name", "age", "job"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(response.choices[0].message.content)
print(data["name"], data["age"], data["job"])

Nested structures

Schemas can include arrays, nested objects, and enums:

{
  "type": "object",
  "properties": {
    "order_id": {"type": "string"},
    "status": {
      "type": "string",
      "enum": ["pending", "paid", "shipped", "done"]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "quantity": {"type": "integer"},
          "price": {"type": "number"}
        },
        "required": ["name", "quantity", "price"],
        "additionalProperties": false
      }
    }
  },
  "required": ["order_id", "status", "items"],
  "additionalProperties": false
}