# Structured Output

Structured Outputs ensure model responses conform to predefined formats, enabling type-safe, predictable integration with your applications.

## What are Structured Outputs?

Instead of parsing free-form text, Structured Outputs guarantee the model returns data in a specific format you define—whether simple JSON or complex schemas with nested objects and arrays.


```
Standard Output:               Structured Output:
-------------------           ---------------------
"The user is 25              {
years old and                  "name": "Alice",
lives in Paris."               "age": 25,
                               "location": "Paris"
                            }
```

## Output Modes

### 1. **`text` Mode** (Default)

Standard free-form text responses.


```json
{
  "outputMode": "text",
  "inputs": [
    {"role": "user", "texts": [{"text": "What is Python?"}]}
  ]
}
```

**Response:**


```
Python is a high-level, interpreted programming language...
```

**Use when:**

- Natural conversation
- Creative writing
- Open-ended queries


### 2. **`json` Mode**

Forces the model to return valid JSON. The model determines the structure based on your prompt.


```json
{
  "outputMode": "json",
  "inputs": [
    {
      "role": "user",
      "texts": [{"text": "Extract name, age, and city from: 'Alice is 25 and lives in Paris'"}]
    }
  ]
}
```

**Response:**


```json
{
  "name": "Alice",
  "age": 25,
  "city": "Paris"
}
```

**Key features:**

- **Guarantees valid JSON** - No parsing errors
- **Flexible structure** - Model decides format
- **No schema required** - Just set the mode


**Use when:**

- Need valid JSON but structure varies
- Quick prototyping
- Structure is implied by prompt


### 3. **`json_schema` Mode**

Most powerful option - define exact structure using JSON Schema. The model **guarantees** output matching your schema.


```json
{
  "outputMode": "json_schema",
  "jsonSchema": {
    "id": "user_profile_v1",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "city": {"type": "string"}
      },
      "required": ["name", "age", "city"],
      "additionalProperties": false
    }
  },
  "inputs": [
    {
      "role": "user",
      "texts": [{"text": "Extract: 'Alice is 25 and lives in Paris'"}]
    }
  ]
}
```

**Response (guaranteed structure):**


```json
{
  "name": "Alice",
  "age": 25,
  "city": "Paris"
}
```

**Key features:**

- **100% schema compliance** - No exceptions
- **Type safety** - Integers are integers, strings are strings
- **Validation** - Required fields always present
- **Predictable** - Same structure every time


**Use when:**

- Type safety is critical
- Integrating with typed languages (TypeScript, Go, Rust)
- Database insertions
- API responses


## JSON Schema

### Basic Schema Example


```json
{
  "id": "simple_schema",
  "schema": {
    "type": "object",
    "properties": {
      "task": {"type": "string"},
      "completed": {"type": "boolean"},
      "priority": {"type": "integer", "minimum": 1, "maximum": 5}
    },
    "required": ["task", "completed"]
  }
}
```

### Supported Types

#### Primitives


```json
{
  "type": "object",
  "properties": {
    "text": {"type": "string"},
    "count": {"type": "integer"},
    "price": {"type": "number"},
    "active": {"type": "boolean"},
    "data": {"type": "null"}
  }
}
```

#### Arrays


```json
{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {"type": "string"}
    },
    "scores": {
      "type": "array",
      "items": {"type": "integer"},
      "minItems": 1,
      "maxItems": 10
    }
  }
}
```

#### Nested Objects


```json
{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"}
      },
      "required": ["name", "email"]
    }
  }
}
```

#### Enums


```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "in_progress", "completed", "failed"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  }
}
```

### Advanced Schema Features

#### Constraints


```json
{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "website": {
      "type": "string",
      "format": "uri"
    }
  }
}
```

#### Optional vs Required


```json
{
  "type": "object",
  "properties": {
    "id": {"type": "string"},           // Required (in required array)
    "name": {"type": "string"},         // Required
    "description": {"type": "string"}   // Optional (not in required array)
  },
  "required": ["id", "name"],
  "additionalProperties": false          // Reject unknown properties
}
```

#### Complex Example: E-commerce Order


```json
{
  "id": "order_schema_v2",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "orderId": {"type": "string"},
      "customer": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string", "format": "email"},
          "address": {
            "type": "object",
            "properties": {
              "street": {"type": "string"},
              "city": {"type": "string"},
              "zipCode": {"type": "string"}
            },
            "required": ["street", "city", "zipCode"]
          }
        },
        "required": ["name", "email", "address"]
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "productId": {"type": "string"},
            "name": {"type": "string"},
            "quantity": {"type": "integer", "minimum": 1},
            "price": {"type": "number", "minimum": 0}
          },
          "required": ["productId", "name", "quantity", "price"]
        },
        "minItems": 1
      },
      "total": {"type": "number", "minimum": 0},
      "status": {
        "type": "string",
        "enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
      }
    },
    "required": ["orderId", "customer", "items", "total", "status"],
    "additionalProperties": false
  }
}
```

## Use Cases

### 1. Data Extraction

Extract structured information from unstructured text:


```python
response = requests.post(
    'https://api.freddy.aitronos.com/v1/model/response',
    json={
        "model": "gpt-4.1",
        "outputMode": "json_schema",
        "jsonSchema": {
            "id": "contact_extraction",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "phone": {"type": "string"},
                    "company": {"type": "string"}
                },
                "required": ["name"]
            }
        },
        "inputs": [{
            "role": "user",
            "texts": [{"text": "Extract contact: John Doe, john@example.com, works at Acme Corp"}]
        }]
    }
)
```

### 2. API Response Generation

Generate API-ready responses:


```javascript
const response = await fetch('/v1/model/response', {
  method: 'POST',
  body: JSON.stringify({
    model: 'gpt-4.1',
    outputMode: 'json_schema',
    jsonSchema: {
      id: 'api_response',
      schema: {
        type: 'object',
        properties: {
          success: { type: 'boolean' },
          data: {
            type: 'object',
            properties: {
              userId: { type: 'string' },
              message: { type: 'string' }
            }
          },
          error: {
            type: 'object',
            properties: {
              code: { type: 'string' },
              message: { type: 'string' }
            }
          }
        },
        required: ['success']
      }
    },
    inputs: [{
      role: 'user',
      texts: [{ text: 'Generate success response for user creation' }]
    }]
  })
});
```

### 3. Database Record Generation

Create type-safe database entries:


```python
# Generate database record
schema = {
    "id": "user_record",
    "schema": {
        "type": "object",
        "properties": {
            "id": {"type": "string"},
            "username": {"type": "string"},
            "email": {"type": "string", "format": "email"},
            "role": {"type": "string", "enum": ["user", "admin", "moderator"]},
            "created_at": {"type": "string", "format": "date-time"},
            "active": {"type": "boolean"}
        },
        "required": ["id", "username", "email", "role", "active"]
    }
}

result = generate_response(outputMode="json_schema", jsonSchema=schema)

# Direct database insertion (no validation needed!)
db.users.insert_one(result)
```

### 4. TypeScript Integration

Generate type-safe responses for TypeScript:


```typescript
// Define TypeScript interface
interface UserProfile {
  id: string;
  name: string;
  age: number;
  email: string;
  interests: string[];
}

// Matching JSON Schema
const schema = {
  id: 'user_profile',
  schema: {
    type: 'object',
    properties: {
      id: { type: 'string' },
      name: { type: 'string' },
      age: { type: 'integer' },
      email: { type: 'string', format: 'email' },
      interests: { type: 'array', items: { type: 'string' } }
    },
    required: ['id', 'name', 'age', 'email', 'interests']
  }
};

// API call with type safety
const response = await createResponse({
  outputMode: 'json_schema',
  jsonSchema: schema,
  inputs: [...]
});

const user: UserProfile = response.output[0].content[0].data; // Type-safe!
```

## Comparison: JSON vs JSON Schema

| Feature | `json` Mode | `json_schema` Mode |
|  --- | --- | --- |
| **Valid JSON** | ✅ Guaranteed | ✅ Guaranteed |
| **Structure control** | ❌ Model decides | ✅ You define |
| **Type enforcement** | ❌ Best effort | ✅ Strict |
| **Required fields** | ❌ May be missing | ✅ Always present |
| **Schema validation** | ❌ None | ✅ 100% compliant |
| **Setup complexity** | Simple | Requires schema |
| **Use case** | Prototyping | Production |


## Best Practices

### ✅ DO

- **Use `json_schema` for production** - Type safety prevents runtime errors
- **Version schema IDs** - `user_profile_v2` for tracking changes
- **Set `additionalProperties: false`** - Reject unexpected fields
- **Use enums for fixed values** - Ensures valid options
- **Document your schemas** - Add descriptions for maintainability
- **Test schemas** - Validate with sample prompts before deployment


### ❌ DON'T

- **Over-constrain schemas** - Too strict may fail to generate
- **Use `json` mode for typed systems** - Use `json_schema` instead
- **Forget required fields** - Model won't generate without them
- **Nest too deeply** - Keep schemas under 5 levels deep
- **Skip ID fields** - Always provide schema IDs for caching


## Troubleshooting

### Schema Validation Errors


```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid JSON Schema: property 'age' must be of type 'integer'",
    "code": "invalid_schema"
  }
}
```

**Solution:** Validate your schema against JSON Schema Draft 2020-12 specification.

### Missing Required Fields


```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "jsonSchema is required when outputMode is 'json_schema'",
    "code": "missing_parameter",
    "param": "jsonSchema"
  }
}
```

**Solution:** Always provide `jsonSchema` when using `json_schema` mode.

### Schema Too Complex

If the model struggles to generate output matching a complex schema:

- Simplify nested structures
- Remove overly strict constraints
- Split into multiple requests
- Use `strict: false` for best-effort compliance


## FAQ

**Q: Can I use `json` mode without a schema?**
A: Yes, `json` mode returns valid JSON without requiring a schema.

**Q: What JSON Schema version is supported?**
A: JSON Schema Draft 2020-12.

**Q: Is `json_schema` mode slower?**
A: Slightly (~5-10%), but negligible compared to the value of guaranteed structure.

**Q: Can the model fail to generate valid output?**
A: With `strict: true`, the model always produces valid schema-compliant output. With `strict: false`, it makes best effort.

**Q: How do I handle optional fields?**
A: Don't include them in the `required` array in your schema.

**Related:**

- [Create Model Response](/docs/api-reference/responses/create) - API reference
- [Function Calling](/docs/documentation/core-concepts/function-calling) - Structured tool outputs
- [Best Practices](/docs/documentation/best-practices) - Optimization tips