Skip to main content
Structured outputs ensure LLM responses follow specific formats, making them easier to use in your applications. For more advanced structured data requirements, you may also want to check out our Tool Calling documentation.

​
What are Structured Outputs?

Structured outputs define formats LLMs must follow when generating responses:
  • Consistent response formats
  • Easier parsing and validation
  • More reliable integration with your applications
  • Less error handling
Examples include customer records, product information, and analytical results.

​
Creating Structured Outputs with JSON Schema

To add a JSON schema to your prompt template:
  1. Edit your prompt template
  2. Click “Add Response Format”
  3. Select “JSON Schema”
  4. Define your schema structure

​
Example: Customer Review Analysis Schema

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positive", "neutral", "negative"],
      "description": "The overall sentiment of the review"
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of topics mentioned in the review"
    },
  },
  "required": ["sentiment", "topics"]
}

​
Using Variables in Structured Outputs

You can make your schemas dynamic by using template variables:
Variables in structured outputs only work with Jinja2 format with the Jinja2 option enabled. F-string format isn’t supported.

​
Interactive Mode

When using the interactive schema editor, you can add variables in two ways:
  1. For enum values: Click the enum field and toggle the switch to “Use Variable”
  1. For text/string values: Type {{ variable_name }} directly in any text field

​
JSON Mode

Variables must be in quotes, except for enum variables:
Jinja2
{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": {name: "sentiment_options", type: "enum_variable"},
      "description": "The sentiment of the {{ content_type }}"
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of topics mentioned in the {{ document_type }}"
    }
  }
}
When running the prompt, provide your variables: 
response = pl.run(
   prompt_name="content_analyzer",
   input_variables={
       "text": "I really enjoyed the new restaurant downtown. The food was amazing and the service was excellent.",
       "sentiment_options": ["positive", "neutral", "negative"],
       "document_type": "review",
       "content_type": "customer feedback"
   },
)
For more information on template variables, see our Template Variables documentation.

​
Dynamic Schema Injection with Variable Type

For advanced use cases, you can inject entire schema sections dynamically at runtime using the variable type. This allows you to define different schemas based on runtime conditions without creating multiple prompt templates.

​
How It Works

  1. In the schema editor, select “variable” as the type for a field
  2. Specify a variable name (e.g., userSchema)
  3. At runtime, pass the complete schema object for that variable

​
Example: Dynamic User Schema

In your prompt template schema: 
{
  "type": "object",
  "properties": {
    "user_data": {
      "type": "variable",
      "name": "userSchema"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "timestamp": { "type": "string" },
        "version": { "type": "string" }
      }
    }
  }
}
At runtime, provide the complete schema: 
response = pl.run(
   prompt_name="dynamic_processor",
   input_variables={
       "userSchema": {
           "type": "object",
           "properties": {
               "name": { "type": "string" },
               "age": { "type": "number" },
               "preferences": {
                   "type": "array",
                   "items": { "type": "string" }
               }
           },
           "required": ["name", "age"]
       }
   }
)
The user_data field will be replaced entirely with the schema you provide, allowing different structures for different use cases.

​
Important Notes

  • Variable schemas only work with Jinja2 template format
  • The entire field is replaced with the provided schema object
  • Ensure the injected schema is valid JSON schema syntax

​
Best Practices

  • For enum values: Use {name: "variable_name", type: "enum_variable"} in JSON mode or the variable selector in interactive mode
  • For text variables: Include them within quotes as {{ variable_name }} in both modes
  • For dynamic schemas: Use type: "variable" with a descriptive variable name
  • Only Jinja2 format works for variables in structured outputs
  • Ensure all variables used in the schema are provided
  • Use proper JSON formatting with variables
⌘I