ProductsPrompt management

Structured output

Define a JSON schema, deploy it with a prompt version, invoke the prompt, and verify the response.

Structured output constrains a prompt response to a JSON schema. This workflow creates a prompt version with a strict schema, deploys it, calls the deployed prompt, and parses the returned JSON.

New to prompts? Start with the Prompt management quickstart. For prompt schema, version pinning, and deployment behavior, see Advanced configurations.

Prerequisites

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_PROMPT_ID="YOUR_PROMPT_ID"

Configure and deploy in the platform

1

Add the schema

Open the prompt editor. In model settings, set Response format to JSON Schema, then click Add schema.

Model settings with Response format set to JSON Schema and the Add schema action visible
Select JSON Schema as the response format and add a schema.
2

Define and save the schema

Paste a schema or use the schema generator. For strict output, list every property in required and set additionalProperties to false.

Add response format dialog containing a custom JSON schema and a Save action
Define the response schema, then save it to the prompt draft.
3

Commit and deploy

Commit the prompt draft to create a version, then deploy that version. Calls that omit a version use the deployed version.

4

Invoke and verify

Call the prompt with its variables. Parse choices[0].message.content as JSON and verify that the required fields are present. The complete request is shown below.

Complete API workflow

The example below creates and deploys a prompt version with a deterministic schema, invokes the deployed prompt, and asserts the promised response shape.

pip install requests
Python
import json
import os
import requests
API_BASE = "https://api.respan.ai/api"
API_KEY = os.environ["RESPAN_API_KEY"]
PROMPT_ID = os.environ["RESPAN_PROMPT_ID"]
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
version_payload = {
    "messages": [
        {"role": "system", "content": "You write accurate, concise animal facts."},
        {
            "role": "user",
            "content": "Give one short, surprising fun fact about {{animal}}.",
        },
    ],
    "model": "gpt-5.5",
    "response_format": {
        "type": "json_schema",
        "json_schema": {
            "name": "fun_fact",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "animal": {"type": "string"},
                    "fact": {"type": "string"},
                },
                "required": ["animal", "fact"],
                "additionalProperties": False,
            },
        },
    },
}
version_response = requests.post(
    f"{API_BASE}/prompts/{PROMPT_ID}/versions/",
    headers=headers,
    json=version_payload,
    timeout=30,
)
version_response.raise_for_status()
commit_response = requests.post(
    f"{API_BASE}/prompts/{PROMPT_ID}/commits/",
    headers=headers,
    json={"description": "Add strict fun-fact output"},
    timeout=30,
)
commit_response.raise_for_status()
version = commit_response.json()["version"]
deployment_response = requests.post(
    f"{API_BASE}/prompts/{PROMPT_ID}/deployments/",
    headers=headers,
    json={"version": version},
    timeout=30,
)
deployment_response.raise_for_status()
completion_response = requests.post(
    f"{API_BASE}/chat/completions",
    headers=headers,
    json={
        "prompt": {
            "prompt_id": PROMPT_ID,
            "schema_version": 2,
            "variables": {"animal": "octopus"},
        }
    },
    timeout=60,
)
completion_response.raise_for_status()
content = completion_response.json()["choices"][0]["message"]["content"]
result = json.loads(content)
assert set(result) == {"animal", "fact"}
assert result["animal"].lower() == "octopus"
print(json.dumps(result, indent=2))

Expected result

The fact text can vary, but the response must contain exactly the two required fields:

{
  "animal": "octopus",
  "fact": "An octopus has three hearts."
}

Open the Logs page and select the request to verify the deployed prompt ID, model, request variables, and structured output captured on the span.

Troubleshooting

  • The prompt call uses an older schema. Confirm that the version containing response_format is deployed, or pin the intended version explicitly.
  • The provider rejects the schema. In strict mode, every property must be required and the object must set additionalProperties: false. Also confirm that the selected model supports structured output.
  • json.loads or JSON.parse fails. Inspect the raw message.content and the request log. Confirm that the prompt version—not only the caller—contains the response format.
  • A prompt variable is missing. The keys under variables must match the {{variable}} names in the deployed messages.
  • The version request returns an error. Check the Prompt Versions API for the current schema and verify that the API key can edit the prompt.
  • Deployment says the version is still a draft. Commit the current draft with POST /prompts/{prompt_id}/commits/, then deploy the returned version number with POST /prompts/{prompt_id}/deployments/.

Prompt schema v2 fields such as schema_version and patch are best sent with raw HTTP requests. OpenAI SDK validation can strip fields it does not recognize.