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

# Structured output

> Ask compatible models to return valid JSON or JSON that follows a schema.

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```python theme={null}
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:

```json theme={null}
{
  "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
}
```

## Structured output vs. function calling

| Feature       | Structured output                      | Function calling                |
| ------------- | -------------------------------------- | ------------------------------- |
| Main goal     | Return predictable JSON                | Select and call external tools  |
| Typical use   | Extraction, routing, generated configs | Database queries, actions, APIs |
| Executes code | No                                     | Yes, in your application        |

## Notes

* Prefer JSON Schema for production workflows that require stable fields.
* Add field descriptions when the schema is complex.
* Still validate and handle parse errors in your application.
* Strict schema support depends on the selected model.

## Next steps

* [Reasoning models](/en/guide/reasoning)
* [Function calling](/en/guide/function-calling)