Skip to content
Last updated

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.

{
  "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.

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

Response:

{
  "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.

{
  "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):

{
  "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

{
  "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

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

Arrays

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

Nested Objects

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

Enums

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

Advanced Schema Features

Constraints

{
  "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

{
  "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

{
  "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:

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:

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:

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

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

Featurejson Modejson_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 complexitySimpleRequires schema
Use casePrototypingProduction

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

{
  "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

{
  "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:

Previous page
Next page