Structured output

Make a prompt return JSON that matches a schema.

Attach a JSON schema to a prompt, and every call to that prompt returns JSON in that shape. The schema is saved with the prompt version, so your code doesn’t send it.

Set it up in the editor

Open the model settings

Go to Gateway › Prompts and open your prompt. In the side panel’s Settings tab, click the settings button next to Model settings.

Choose a response format

Set Response format:

Option	Output
Text	Free text (the default).
JSON Object	Valid JSON, with no fixed shape.
JSON Schema	JSON that matches your schema.

Add the schema

For JSON Schema, open the Schema menu and pick a saved schema, or click New and paste a definition. Examples loads a sample schema, and Generate writes one from a description. To save the schema for reuse, fill in Name. Click Save.

JSON

Copy

{
  "name": "ticket_triage",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "category": { "type": "string", "enum": ["billing", "login", "bug", "feature_request", "other"] },
      "urgency": { "type": "string", "enum": ["low", "medium", "high"] },
      "summary": { "type": "string" }
    },
    "required": ["category", "urgency", "summary"],
    "additionalProperties": false
  }
}

The editor requires a top-level name, and a schema of "type": "object" with at least one property. required can only list properties that exist. If additionalProperties is missing, the editor sets it to false.

Turn on Enforce format

Set Enforce format to True. API calls use the response format only when this is on.

Run in the editor always applies the response format, so a test run can return JSON while your API calls don’t. Check Enforce format before you commit.

Commit and deploy

Commit the version and deploy it, as in the Quickstart. Calls without a version use the deployed version.

Call the prompt

Call the prompt as usual, then parse the message content as JSON.

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key=os.environ["RESPAN_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-5.5",  # the prompt's saved model is used
    messages=[],
    extra_body={
        "prompt": {
            "prompt_id": "YOUR_PROMPT_ID",
            "schema_version": 2,
            "variables": {"ticket_body": "I was charged twice for the Team plan this month."},
        }
    },
)

triage = json.loads(response.choices[0].message.content)
print(triage["category"], triage["urgency"])

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.respan.ai/api/",
  apiKey: process.env.RESPAN_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-5.5", // the prompt's saved model is used
  messages: [],
  // @ts-expect-error `prompt` is a Respan field
  prompt: {
    prompt_id: "YOUR_PROMPT_ID",
    schema_version: 2,
    variables: { ticket_body: "I was charged twice for the Team plan this month." },
  },
});

const triage = JSON.parse(response.choices[0].message.content ?? "{}");
console.log(triage.category, triage.urgency);

The content is a JSON string in your schema’s shape:

{
  "category": "billing",
  "urgency": "high",
  "summary": "Customer was charged twice for the Team plan and wants the duplicate refunded."
}

For what schema_version: 2 does, see Prompt schema.

Saved schemas

A schema saved with a Name shows up in the Schema menu of every prompt. Picking one copies it into the prompt version, so later edits to the saved schema don’t change prompts that already use it.

To add, edit, or delete saved schemas, click Schemas at the top right of the prompt editor, or Manage in the Schema menu. In the Schemas list, click New schema to add one, click a schema to edit it, or open its ⋯ menu to delete it. You can also use the response format presets API.

Troubleshooting

• The response isn’t JSON. Open the deployed version and check that Enforce format is True. Also check that the model supports structured output.
• The provider rejects the schema. With "strict": true, OpenAI models need every property listed in required and "additionalProperties": false. For an optional field, use a type like ["string", "null"].
• The call uses an older schema. Deploy the version with the new schema, or pin it with version.