Overview
Structured outputs enable you to enforce specific response formats from Perplexity’s models, ensuring consistent, machine-readable data that can be directly integrated into your applications without manual parsing.
We currently support JSON Schema structured outputs. To enable structured outputs, add a response_format field to your request with the following structure:
{
"response_format": {
"type": "json_schema",
"json_schema": {
"schema": { /* your JSON schema object */ }
}
}
}
max_tokens.
Improve Schema Compliance: Give the LLM some hints about the output format in your prompts to improve adherence to the structured format.For example, include phrases like “Please return the data as a JSON object with the following structure…” or “Extract the information and format it as specified in the schema.”
The first request with a new JSON Schema expects to incur delay on the first token. Typically, it takes 10 to 30 seconds to prepare the new schema, and may result in timeout errors. Once the schema has been prepared, the subsequent requests will not see such delay.
Examples
1. Financial Analysis
from perplexity import Perplexity
from typing import List, Optional
from pydantic import BaseModel
class FinancialMetrics(BaseModel):
company: str
quarter: str
revenue: float
net_income: float
eps: float
revenue_growth_yoy: Optional[float] = None
key_highlights: Optional[List[str]] = None
client = Perplexity()
completion = client.chat.completions.create(
model="sonar-pro",
messages=[
{
"role": "user",
"content": "Analyze the latest quarterly earnings report for Apple Inc. Extract key financial metrics."
}
],
response_format={
"type": "json_schema",
"json_schema": {
"schema": FinancialMetrics.model_json_schema()
}
}
)
metrics = FinancialMetrics.model_validate_json(completion.choices[0].message.content)
print(f"Revenue: ${metrics.revenue}B")
from perplexity import Perplexity
from pydantic import BaseModel
class ContactInfo(BaseModel):
email: str
client = Perplexity()
completion = client.chat.completions.create(
model="sonar",
messages=[
{
"role": "user",
"content": "Find the direct email address for the investor relations contact at Tesla Inc."
}
],
response_format={
"type": "json_schema",
"json_schema": {
"schema": ContactInfo.model_json_schema()
}
}
)
contact = ContactInfo.model_validate_json(completion.choices[0].message.content)
print(f"Investor Relations Email: {contact.email}")
Best Practices
For Python users, we recommend using the Pydantic library to generate JSON schema.
Unsupported JSON Schemas
Recursive JSON schema is not supported. As a result of that, unconstrained objects are not supported either. Here are a few examples of unsupported schemas:
# UNSUPPORTED!
from typing import Any
class UnconstrainedDict(BaseModel):
unconstrained: dict[str, Any]
class RecursiveJson(BaseModel):
value: str
child: list["RecursiveJson"]
Links in JSON Responses: Requesting links as part of a JSON response may not always work reliably and can result in hallucinations or broken links. Models may generate invalid URLs when forced to include links directly in structured outputs.To ensure all links are valid, use the links returned in the citations or search_results fields from the API response. Never count on the model to return valid links directly as part of the JSON response content.
Perplexity’s JSON Schema Implementation
Perplexity’s structured outputs implementation has several key differences compared to other providers:
Simplified Schema Definition
- Optional naming: Unlike other providers that require explicit schema names, Perplexity automatically handles schema naming with sensible defaults
- Flexible strictness: Schema validation is handled automatically without requiring manual strictness configuration
- Streamlined syntax: You only need to provide the core schema object without additional wrapper fields
Other Providers:
{
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "financial_data",
"strict": true,
"schema": { /* your schema */ }
}
}
}
{
"response_format": {
"type": "json_schema",
"json_schema": {
"schema": { /* your schema */ }
}
}
}
Enhanced Error Handling
- Clear error messages: When schemas fail validation, you’ll receive specific, actionable error messages
- Recursion protection: Built-in safeguards prevent infinite recursion in complex nested schemas
- Constraint validation: Automatic detection and clear messaging for unsupported features like unconstrained objects
Schema Compatibility
While Perplexity supports standard JSON Schema syntax, some advanced features may not be available:
- Recursive schemas are not supported for performance and reliability reasons
- Unconstrained objects (like
dict[str, Any]) are automatically detected and rejected
- Complex reference patterns may require simplification
This approach prioritizes reliability and performance while maintaining compatibility with most common JSON Schema use cases.
Structured Outputs for Reasoning Models
When using structured outputs with reasoning models like sonar-reasoning-pro, the response will include a <think> section containing reasoning tokens, immediately followed by the structured output. The response_format parameter does not remove these reasoning tokens from the output, so the final response will need to be parsed manually.
Sample Response:
<think>
I need to provide information about France in a structured JSON format with specific fields: country, capital, population, official_language.
For France:
- Country: France
- Capital: Paris
- Population: About 67 million (as of 2023)
- Official Language: French
Let me format this information as required.
</think>
{"country":"France","capital":"Paris","population":67750000,"official_language":"French"}
