Structured Output
Want your AI responses as neat and tidy as a Marie Kondo-approved closet? Structured output lets you define exactly how you want your data formatted, making it perfect for building APIs, processing forms, or any time you need data in a specific shape.
Quick Start
Here's how to get structured data from your AI:
use EchoLabs\Prism\Prism;
use EchoLabs\Prism\Enums\Provider;
use EchoLabs\Prism\Schema\ObjectSchema;
use EchoLabs\Prism\Schema\StringSchema;
$schema = new ObjectSchema(
name: 'movie_review',
description: 'A structured movie review',
properties: [
new StringSchema('title', 'The movie title'),
new StringSchema('rating', 'Rating out of 5 stars'),
new StringSchema('summary', 'Brief review summary')
],
requiredFields: ['title', 'rating', 'summary']
);
$response = Prism::structured()
->using(Provider::OpenAI, 'gpt-4o')
->withSchema($schema)
->withPrompt('Review the movie Inception')
->generate();
// Access your structured data
$review = $response->structured;
echo $review['title']; // "Inception"
echo $review['rating']; // "5 stars"
echo $review['summary']; // "A mind-bending..."
TIP
This is just a basic example of schema usage. Check out our dedicated schemas guide to learn about all available schema types, nullable fields, and best practices for structuring your data.
Understanding Output Modes
Different AI providers handle structured output in two main ways:
- Structured Mode: Some providers support strict schema validation, ensuring responses perfectly match your defined structure.
- JSON Mode: Other providers simply guarantee valid JSON output that approximately matches your schema.
NOTE
Check your provider's documentation to understand which mode they support. Provider support can vary by model, so always verify capabilities for your specific use case.
Provider-Specific Options
Providers may offer additional options for structured output. For example, OpenAI supports a "strict mode" for even tighter schema validation:
use EchoLabs\Prism\Prism;
use EchoLabs\Prism\Enums\Provider;
$response = Prism::structured()
->withProviderMeta(Provider::OpenAI, [
'schema' => [
'strict' => true
]
])
// ... rest of your configuration
TIP
Check the provider-specific documentation pages for additional options and features that might be available for structured output.
Response Handling
When working with structured responses, you have access to both the structured data and metadata about the generation:
use EchoLabs\Prism\Prism;
$response = Prism::structured()
->withSchema($schema)
->generate();
// Access the structured data as a PHP array
$data = $response->structured;
// Get the raw response text if needed
echo $response->text;
// Check why the generation stopped
echo $response->finishReason->name;
// Get token usage statistics
echo "Prompt tokens: {$response->usage->promptTokens}";
echo "Completion tokens: {$response->usage->completionTokens}";
// Access provider-specific response data
$rawResponse = $response->response;
TIP
Always validate the structured data before using it in your application:
if ($response->structured === null) {
// Handle parsing failure
}
if (!isset($response->structured['required_field'])) {
// Handle missing required data
}
Common Settings
Structured output supports several configuration options to fine-tune your generations:
Model Configuration
maxTokens
- Set the maximum number of tokens to generatetemperature
- Control output randomness (provider-dependent)topP
- Alternative to temperature for controlling randomness (provider-dependent)
Input Methods
withPrompt
- Single prompt for generationwithMessages
- Message history for more contextwithSystemPrompt
- System-level instructions
Request Configuration
withClientOptions
- Set HTTP client options (e.g., timeouts)withClientRetry
- Configure automatic retries on failuresusingProviderConfig
- Override provider configurationwithProviderMeta
- Set provider-specific options
NOTE
Unlike text generation, structured output does not support tools/function calling. For those features, use the text generation API instead.
See the Text Generation documentation for comparison with standard text generation capabilities.
Error Handling
When working with structured output, it's especially important to handle potential errors:
use EchoLabs\Prism\Prism;
use EchoLabs\Prism\Enums\Provider;
use EchoLabs\Prism\Exceptions\PrismException;
try {
$response = Prism::structured()
->using('anthropic', 'claude-3-sonnet')
->withSchema($schema)
->withPrompt('Generate product data')
->generate();
} catch (PrismException $e) {
// Handle validation or generation errors
Log::error('Structured generation failed:', [
'error' => $e->getMessage()
]);
}
IMPORTANT
Always validate the structured response before using it in your application, as different providers may have varying levels of schema adherence.