JSON Mode

​

When to use JSON mode

• Flexible data structures: When the exact output structure may vary based on input
• Rapid prototyping: Quick experimentation without defining formal schemas
• Simple JSON needs: Cases where valid JSON is sufficient without strict validation

• Production applications requiring guaranteed schema compliance
• Data that feeds directly into typed systems or databases
• Cases where validation and retry logic would be complex

​

Enabling JSON mode in Freeplay

​

In the prompt editor

1. Open your prompt template in the Freeplay editor
2. Navigate to the output configuration section
3. Select “Enable JSON output”
4. Save your prompt template

​

In your prompts

You are a helpful assistant that outputs JSON.

Extract the key information from the following text and return it as JSON.
Include fields for name, date, and main topics discussed.

Your response should look like:

{
  "name": <name>,
  "date": <date>,
  "topics": <topics discussed>
}

​

Best practices

​

Always instruct the model

Return your response as valid JSON with the following structure:
{
  "summary": "brief summary here",
  "key_points": ["point 1", "point 2"],
  "sentiment": "positive/negative/neutral"
}

​

Validate the output

import json

try:
data = json.loads(response.choices[0].message.content)

    # Validate expected fields
    if "summary" not in data:
        # Handle missing fields
        pass

except json.JSONDecodeError: # Handle parse errors (rare with JSON mode)
pass

​

Provide examples

Example output format:
{
"title": "Meeting Notes",
"date": "2024-10-15",
"attendees": ["Alice", "Bob"],
"action_items": [
{"task": "Review document", "owner": "Alice", "due": "2024-10-20"}
]
}

​

Handle edge cases

• Token limit reached: Output may be incomplete JSON
• Model refuses: Safety refusals may not be valid JSON

if response.choices[0].finish_reason != "stop":
    # Handle incomplete response
    print(f"Response incomplete: {response.choices[0].finish_reason}")

​

Recording to Freeplay

from freeplay import RecordPayload, CallInfo

# Record the completion

session = fp_client.sessions.create()
payload = RecordPayload(
project_id=project_id,
all_messages=[
\*formatted_prompt.llm_prompt,
{
"role": response.choices[0].message.role,
"content": response.choices[0].message.content,
}
],
inputs={"text": user_input},
session_info=session.session_info,
prompt_version_info=formatted_prompt.prompt_info,
call_info=CallInfo.from_prompt_info(formatted_prompt.prompt_info, start, end),
)

fp_client.recordings.create(payload)

​

JSON mode vs structured outputs

​

Troubleshooting

• Solution: Ensure “JSON” appears in your prompt instructions. Add explicit JSON format instructions.

• Solution: Check finish_reason. If it’s length, increase max_tokens. If it’s content_filter, adjust your input.

• Solution: Provide clear examples in your prompt. Consider using structured outputs if you need guaranteed schema compliance.