Structured Output (JSON)
Get machine-readable JSON back so your code can use the result directly.
Free-form text is hard for programs to consume. When you need the output in your code, ask the model to return JSON that matches a schema you describe.
How to get reliable JSON
- Describe the exact shape and field names.
- Say Return only valid JSON, no extra text.
- Use temperature 0 for consistency.
- Many APIs offer a JSON mode or schema parameter that guarantees valid JSON.
Then JSON.parse the result and use it like any other object.
Example
{
"instruction": "Extract the person's details as JSON with keys name, role, company. Return only JSON.",
"input": "Aisha Khan is the CTO at Northwind.",
"expected_output": {
"name": "Aisha Khan",
"role": "CTO",
"company": "Northwind"
}
}When to use it
- A data pipeline calls an LLM to extract invoice fields and parses the JSON response directly into a database insert without manual mapping.
- A product catalogue tool prompts the model to return item attributes as a JSON array so the front end can render each card without extra processing.
- A sentiment-analysis microservice validates that every AI response is valid JSON with a 'label' and 'confidence' key before storing the result.
More examples
Prompt for JSON object output
Instructs the model to reply with JSON only, then parses the string into a Python dict.
import json
from openai import OpenAI
client = OpenAI()
r = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content':
'Extract the name, date, and amount from this invoice text: '
'"Invoice for John Smith on 2025-06-01 for $1,200.00". '
'Reply with JSON only. No explanation.'
}]
)
data = json.loads(r.choices[0].message.content)
print(data)Use response_format JSON mode
Enables JSON mode via response_format so the API guarantees the output is valid JSON.
import json
from openai import OpenAI
client = OpenAI()
r = client.chat.completions.create(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': 'You are a JSON API. Always return valid JSON.'},
{'role': 'user', 'content': 'Give me a recipe for pancakes with fields: name, ingredients (list), steps (list).'}
],
response_format={'type': 'json_object'}
)
recipe = json.loads(r.choices[0].message.content)
print(recipe['name'])
print(recipe['ingredients'])Validate JSON output before using it
Parses the JSON and asserts required keys exist before the result is passed to downstream code.
import json
from openai import OpenAI
SCHEMA_KEYS = {'label', 'confidence'}
client = OpenAI()
r = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content':
'Classify the sentiment of "I love this!" '
'Return JSON with keys label (POSITIVE/NEGATIVE) and confidence (0-1).'
}],
response_format={'type': 'json_object'}
)
try:
result = json.loads(r.choices[0].message.content)
assert SCHEMA_KEYS <= result.keys(), 'Missing keys'
print(result)
except (json.JSONDecodeError, AssertionError) as e:
print('Invalid response:', e)
Discussion