Structured Output

Overview

By default, an LLM returns free-form text. When you define an outputs in your .prompty frontmatter, the runtime converts it to the provider’s response_format parameter so the model is constrained to return valid JSON matching your schema. The processor then automatically parses the JSON string into a Python dict or JavaScript object — no manual JSON.parse() needed.

flowchart LR
    A["outputs\n(YAML)"] --> B["_output_schema\n_to_wire()\nconversion"]
    B --> C["response_format\njson_schema\n→ sent to LLM"]
    C --> D["LLM response\nvalid JSON"]
    D --> E["Processor\nJSON.parse"]
    E --> F["Typed\ndict / obj"]

    style A fill:#dbeafe,stroke:#3b82f6,color:#1e40af
    style B fill:#bfdbfe,stroke:#1d4ed8,color:#1e3a8a
    style C fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style D fill:#e5e7eb,stroke:#6b7280,color:#374151
    style E fill:#a7f3d0,stroke:#10b981,color:#065f46
    style F fill:#d1fae5,stroke:#10b981,color:#065f46

---

Defining Output Schema

Add an outputs block to your frontmatter with the properties you expect in the response. Each property has a kind (type) and optional description.

weather.prompty

---
name: weather-report
model:
  id: gpt-4o-mini
  provider: openai
  apiType: chat
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
outputs:
  - name: city
    kind: string
    description: The city name
  - name: temperature
    kind: integer
    description: Temperature in degrees Fahrenheit
  - name: conditions
    kind: string
    description: Current weather conditions
---
system:
You are a weather assistant. Return the current weather for the requested city.

user:
What's the weather in {{city}}?

The runtime converts this to an OpenAI-compatible response_format with type: "json_schema", ensuring the LLM must return a JSON object with exactly those three fields.

---

How It Works

Under the hood, the executor performs three steps when outputs is present:

1. Schema conversion — _output_schema_to_wire() translates each Property (with kind, description, required) into a standard JSON Schema object. The result is wrapped in an OpenAI response_format parameter:

   {
     "type": "json_schema",
     "json_schema": {
       "name": "output_schema",
       "strict": true,
       "schema": {
         "type": "object",
         "properties": {
           "city": { "type": "string", "description": "The city name" },
           "temperature": { "type": "integer", "description": "Temperature in degrees Fahrenheit" },
           "conditions": { "type": "string", "description": "Current weather conditions" }
         },
         "required": ["city", "temperature", "conditions"],
         "additionalProperties": false
       }
     }
   }

2. LLM constrained generation — the model is forced to return valid JSON matching the schema. No malformed output, no missing fields.

3. Processor auto-parse — the processor detects that outputs is defined and calls json.loads() on the response content, returning a native dict (Python) or object (JavaScript) instead of a raw string.

Note

Structured output uses OpenAI’s strict mode — additionalProperties: false is set automatically, and all properties are marked as required. This guarantees the model returns exactly the fields you specified.

---

Usage

With structured output, invoke() returns a StructuredResult — a dict/object subclass that you can use just like a regular dictionary, but that also carries the raw JSON for efficient type casting.

Python

from prompty import invoke

result = invoke("weather.prompty", inputs={"city": "Seattle"})

# result is a StructuredResult (dict subclass) — use like a dict
print(result["city"])         # "Seattle"
print(result["temperature"])  # 62
print(result["conditions"])   # "Partly cloudy"
print(type(result))           # <class 'StructuredResult'>
isinstance(result, dict)      # True — fully backward compatible

Python (async)

from prompty import invoke_async

result = await invoke_async("weather.prompty", inputs={"city": "Seattle"})
print(result["temperature"])  # 62

TypeScript

import { invoke } from "@prompty/core";

const result = await invoke("weather.prompty", { city: "Seattle" });

// result is a StructuredResult — use like a normal object
console.log(result.city);         // "Seattle"
console.log(result.temperature);  // 62
console.log(result.conditions);   // "Partly cloudy"

C#

using Prompty.Core;

var result = await Pipeline.InvokeAsync("weather.prompty",
    new() { ["city"] = "Seattle" });

// result is a StructuredResult (Dictionary<string, object?> subclass)
if (result is StructuredResult sr)
{
    Console.WriteLine(sr["city"]);         // "Seattle"
    Console.WriteLine(sr["temperature"]);  // 62
    Console.WriteLine(sr["conditions"]);   // "Partly cloudy"
}

Rust

// The outputSchema in the .prompty file is automatically converted
// to OpenAI's response_format parameter. The result comes back as
// a parsed serde_json::Value matching the schema.
let inputs = serde_json::json!({"city": "Seattle"});
let result = prompty::invoke_from_path("weather.prompty", Some(&inputs)).await?;

// result is a serde_json::Value — use like a JSON object
println!("{}", result["city"]);         // "Seattle"
println!("{}", result["temperature"]);  // 62
println!("{}", result["conditions"]);   // "Partly cloudy"

---

Without Output Schema

If you don’t define outputs, the processor returns the raw text content from the LLM response. You can still ask the model to return JSON in your prompt instructions, but there’s no schema enforcement or automatic parsing.

With outputs

# outputs defined → dict returned automatically
result = invoke("weather.prompty", inputs={"city": "Seattle"})
print(type(result))  # <class 'dict'>
print(result["temperature"])  # 62

Without outputs

# No outputs → raw string returned
result = invoke("chat.prompty", inputs={"city": "Seattle"})
print(type(result))  # <class 'str'>
# You'd need to parse manually:
import json
data = json.loads(result)  # may fail if LLM didn't return valid JSON

Caution

Without outputs, the LLM may return malformed JSON, add extra commentary around the JSON block, or omit fields. Always prefer defining a schema when you need structured data.

---

Casting to Typed Objects

StructuredResult is backward-compatible with dict/object usage, but when you need a typed object (dataclass, Pydantic model, class, Zod schema), use cast(). It deserializes directly from the raw JSON string — no intermediate dict→JSON→T round-trip.

Python

from dataclasses import dataclass
from prompty import invoke, cast

@dataclass
class Weather:
    city: str
    temperature: int
    conditions: str

result = invoke("weather.prompty", inputs={"city": "Seattle"})
weather = cast(result, Weather)

print(weather.city)         # "Seattle"
print(weather.temperature)  # 62
print(type(weather))        # <class 'Weather'>

Pydantic models use the optimal model_validate_json() path:

from pydantic import BaseModel
from prompty import invoke, cast

class Weather(BaseModel):
    city: str
    temperature: int
    conditions: str

weather = cast(invoke("weather.prompty", inputs={"city": "Seattle"}), Weather)

Or use the target_type shorthand on invoke / turn:

weather = invoke("weather.prompty", inputs={"city": "Seattle"}, target_type=Weather)

TypeScript

import { invoke, cast } from "@prompty/core";
import { z } from "zod";

const WeatherSchema = z.object({
  city: z.string(),
  temperature: z.number(),
  conditions: z.string(),
});
type Weather = z.infer<typeof WeatherSchema>;

const result = await invoke("weather.prompty", { city: "Seattle" });
const weather = cast<Weather>(result, WeatherSchema.parse);

console.log(weather.city);  // "Seattle"

Or use the typed invoke overload with a validator:

const weather = await invoke(
  "weather.prompty",
  { city: "Seattle" },
  { validator: WeatherSchema.parse }
);
// weather is typed as Weather

C#

using Prompty.Core;

var result = await Pipeline.InvokeAsync("weather.prompty",
    new() { ["city"] = "Seattle" });

// Option 1: Cast after invoke
var weather = ((StructuredResult)result).Cast<WeatherReport>();
Console.WriteLine(weather.City);  // "Seattle"

// Option 2: Generic invoke — cast in one step
var weather2 = await Pipeline.InvokeAsync<WeatherReport>("weather.prompty",
    new() { ["city"] = "Seattle" });

Rust

use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Weather {
    city: String,
    temperature: i32,
    conditions: String,
}

let inputs = serde_json::json!({"city": "Seattle"});
let result = prompty::invoke_from_path("weather.prompty", Some(&inputs)).await?;

// Deserialize the serde_json::Value into a typed struct
let weather: Weather = serde_json::from_value(result)?;

println!("{}", weather.city);         // "Seattle"
println!("{}", weather.temperature);  // 62

Note

cast() uses the raw JSON stringstored inside StructuredResult — it does not serialize back to JSON from the dict and then re-parse. This is the fastest possible path from LLM response to your typed object.

---

Nested Objects

For complex responses, use kind: object with nested properties to define multi-level schemas:

detailed-weather.prompty

---
name: detailed-weather
model:
  id: gpt-4o-mini
  provider: openai
  apiType: chat
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
outputs:
  - name: city
    kind: string
  - name: current
    kind: object
    properties:
        - name: temperature
          kind: integer
          description: Temperature in °F
        - name: humidity
          kind: integer
          description: Humidity percentage
        - name: conditions
          kind: string
    - name: forecast
      kind: array
      description: Next 3 days
---
system:
Return current weather and a 3-day forecast for the requested city.

user:
Weather for {{city}}?

The result is a nested dictionary:

result = invoke("detailed-weather.prompty", inputs={"city": "Portland"})

print(result["city"])                     # "Portland"
print(result["current"]["temperature"])   # 58
print(result["current"]["humidity"])      # 72
print(result["forecast"])                 # [{"day": "Mon", ...}, ...]

Tip

Keep your output schemas as flat as possible — deeply nested schemas increase token usage and can slow down constrained generation. Use nesting only when the data genuinely has hierarchical structure.