Logging Structured Outputs

Overview

When logging requests that use structured outputs (JSON schemas), you need to include the schema configuration in the parameters field of your /log-request call. This allows PromptLayer to properly track and display your structured output configurations alongside your request history.

When to Use This

Use structured output logging when you’re:

Making API calls with JSON schema validation (OpenAI, Anthropic, Google, etc.)
Tracking requests that enforce specific response formats
Analyzing how different schema configurations affect model outputs
Building applications that require reliable, parseable JSON responses

Basic Structure

The structured output configuration goes in the parameters field of your log request, using the response_format key with json_schema configuration:

{
  "provider": "openai",
  "model": "gpt-4",
  "input": {...},
  "output": {...},
  "parameters": {
    "temperature": 0.7,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "YourSchemaName",
        "description": "Description of what this schema represents",
        "schema": {
          "type": "object",
          "properties": {
            // Your JSON schema properties
          },
          "required": ["field1", "field2"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  }
}

Complete Examples

OpenAI with Structured Outputs

import promptlayer
from datetime import datetime

promptlayer.api_key = "your_api_key"

# Make your OpenAI call with structured outputs
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Generate a recipe for chocolate cake"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "Recipe",
            "description": "A structured recipe format",
            "schema": {
                "type": "object",
                "properties": {
                    "recipe_name": {"type": "string"},
                    "ingredients": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "amount": {"type": "string"}
                            },
                            "required": ["name", "amount"]
                        }
                    },
                    "instructions": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["recipe_name", "ingredients", "instructions"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

# Log the request to PromptLayer
promptlayer.log_request(
    provider="openai",
    model="gpt-4",
    input={
        "type": "chat",
        "messages": [{"role": "user", "content": [{"type": "text", "text": "Generate a recipe for chocolate cake"}]}]
    },
    output={
        "type": "chat",
        "messages": [{"role": "assistant", "content": [{"type": "text", "text": response.choices[0].message.content}]}]
    },
    request_start_time=datetime.now(),
    request_end_time=datetime.now(),
    parameters={
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "Recipe",
                "description": "A structured recipe format",
                "schema": {
                    "type": "object",
                    "properties": {
                        "recipe_name": {"type": "string"},
                        "ingredients": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "name": {"type": "string"},
                                    "amount": {"type": "string"}
                                },
                                "required": ["name", "amount"]
                            }
                        },
                        "instructions": {
                            "type": "array",
                            "items": {"type": "string"}
                        }
                    },
                    "required": ["recipe_name", "ingredients", "instructions"],
                    "additionalProperties": False
                },
                "strict": True
            }
        }
    },
    tags=["structured-output", "recipe-generation"],
    api_type="chat-completions"
)

Google Gemini with Structured Outputs

import promptlayer
from datetime import datetime

promptlayer.api_key = "your_api_key"

# Log a Google Gemini request with structured outputs
promptlayer.log_request(
    provider="google",
    model="gemini-3.1-pro-preview",
    input={
        "type": "chat",
        "messages": [{"role": "user", "content": [{"type": "text", "text": "Create a product listing"}]}]
    },
    output={
        "type": "chat",
        "messages": [{"role": "assistant", "content": [{"type": "text", "text": "..."}]}]
    },
    request_start_time=datetime.now(),
    request_end_time=datetime.now(),
    parameters={
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "ProductListing",
                "description": "Product information structure",
                "schema": {
                    "type": "object",
                    "properties": {
                        "product_name": {"type": "string"},
                        "price": {"type": "number"},
                        "description": {"type": "string"},
                        "features": {
                            "type": "array",
                            "items": {"type": "string"}
                        }
                    },
                    "required": ["product_name", "price"],
                    "additionalProperties": False
                },
                "strict": False
            }
        },
        "temperature": 0,
        "maxOutputTokens": 256
    },
    tags=["google", "structured-output"]
)

JavaScript/TypeScript Example

import Promptlayer from 'promptlayer';

const promptlayer = new Promptlayer({ apiKey: 'your_api_key' });

// Make your API call with structured outputs
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Extract contact information' }],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'ContactInfo',
      description: 'Structured contact information',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          email: { type: 'string' },
          phone: { type: 'string' }
        },
        required: ['name', 'email'],
        additionalProperties: false
      },
      strict: true
    }
  }
});

// Log to PromptLayer
await promptlayer.logRequest({
  provider: 'openai',
  model: 'gpt-4',
  input: {
    type: 'chat',
    messages: [{ role: 'user', content: [{ type: 'text', text: 'Extract contact information' }] }]
  },
  output: {
    type: 'chat',
    messages: [{ role: 'assistant', content: [{ type: 'text', text: response.choices[0].message.content }] }]
  },
  request_start_time: new Date().toISOString(),
  request_end_time: new Date().toISOString(),
  parameters: {
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'ContactInfo',
        description: 'Structured contact information',
        schema: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            email: { type: 'string' },
            phone: { type: 'string' }
          },
          required: ['name', 'email'],
          additionalProperties: false
        },
        strict: true
      }
    }
  },
  tags: ['structured-output', 'contact-extraction']
});

REST API Example

If you’re calling the /log-request endpoint directly via REST API:

curl -X POST https://api.promptlayer.com/log-request \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d '{
    "provider": "openai",
    "model": "gpt-4",
    "input": {
      "type": "chat",
      "messages": [{"role": "user", "content": [{"type": "text", "text": "Generate a user profile"}]}]
    },
    "output": {
      "type": "chat",
      "messages": [{"role": "assistant", "content": [{"type": "text", "text": "{\"name\":\"John\",\"age\":30}"}]}]
    },
    "request_start_time": "2024-01-15T10:00:00Z",
    "request_end_time": "2024-01-15T10:00:02Z",
    "parameters": {
      "temperature": 0.7,
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "UserProfile",
          "description": "User profile information",
          "schema": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "age": {"type": "number"},
              "email": {"type": "string"}
            },
            "required": ["name", "age"],
            "additionalProperties": false
          },
          "strict": true
        }
      }
    },
    "tags": ["user-profile", "structured-output"]
  }'

Schema Configuration Details

Key Fields

name (required): A descriptive name for your schema (e.g., “Recipe”, “ContactInfo”)
description (optional): Explains what the schema represents
schema (required): The actual JSON schema definition following JSON Schema specification
strict (optional): When true, enforces strict validation (supported by some providers like OpenAI)

Schema Best Practices

Use clear property names: Make your schema self-documenting
Specify required fields: Use the required array to mark mandatory properties
Set additionalProperties: false: Prevents unexpected fields in the response
Use descriptive types: Leverage JSON Schema’s type system (string, number, array, object, boolean)
Add validation constraints: Use minLength, maxLength, minimum, maximum, etc. when appropriate

Tracking Schema Variations

Use tags and metadata to track different schema versions:

promptlayer.log_request(
    # ... other parameters ...
    parameters={
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "Recipe_v2",  # Version in name
                # ... schema definition ...
            }
        }
    },
    tags=["structured-output", "recipe-v2", "production"],
    metadata={
        "schema_version": "2.0",
        "environment": "production"
    }
)

Common Issues and Solutions

Issue: Schema not showing in PromptLayer dashboard

Solution: Ensure the response_format is nested correctly within the parameters field, not at the top level of your log request.

Issue: Provider rejects the schema

Solution: Different providers have different schema support levels:

OpenAI: Full support with strict: true mode
Anthropic: Supports basic JSON mode
Google: Supports schemas with some limitations

Check your provider’s documentation for specific schema requirements.

Issue: Response doesn’t match schema

Solution:

Verify your schema is valid JSON Schema
Test with strict: true if your provider supports it
Check that your prompt clearly instructs the model about the expected format
Review logged requests in PromptLayer to debug schema mismatches

Get Started

Core Concepts

Providers

Guides

AI Tools

Reference

Deprecated

Logging Structured Outputs

Overview

When to Use This

Basic Structure

Complete Examples

OpenAI with Structured Outputs

Google Gemini with Structured Outputs

JavaScript/TypeScript Example

REST API Example

Schema Configuration Details

Key Fields

Schema Best Practices

Tracking Schema Variations

Common Issues and Solutions

Issue: Schema not showing in PromptLayer dashboard

Issue: Provider rejects the schema

Issue: Response doesn’t match schema

See Also

​Overview

​When to Use This

​Basic Structure

​Complete Examples

​OpenAI with Structured Outputs

​Google Gemini with Structured Outputs

​JavaScript/TypeScript Example

​REST API Example

​Schema Configuration Details

​Key Fields

​Schema Best Practices

​Tracking Schema Variations

​Common Issues and Solutions

​Issue: Schema not showing in PromptLayer dashboard

​Issue: Provider rejects the schema

​Issue: Response doesn’t match schema

​See Also

Overview

When to Use This

Basic Structure

Complete Examples

OpenAI with Structured Outputs

Google Gemini with Structured Outputs

JavaScript/TypeScript Example

REST API Example

Schema Configuration Details

Key Fields

Schema Best Practices

Tracking Schema Variations

Common Issues and Solutions

Issue: Schema not showing in PromptLayer dashboard

Issue: Provider rejects the schema

Issue: Response doesn’t match schema

See Also