Practical AI tutorial
How to Use Structured Outputs for Reliable AI JSON
AI-generated text is useful, but it becomes much more dependable when an application can expect the same fields and data types every time. Structured Outputs let you describe the result you want with a JSON Schema instead of hoping a model follows a formatting instruction.
In this tutorial, you will build a small extraction workflow that turns an unstructured sentence into a predictable event object. The same pattern can power content briefs, lead forms, tool comparisons, customer-support summaries, and other AI workflows where the next step is handled by software rather than a person.
What Structured Outputs solve
Plain prompting can ask an AI model to “return valid JSON,” but that request does not necessarily guarantee that required keys are present, enum values are valid, or nested fields have the expected types. OpenAI’s documentation describes Structured Outputs as a way to make a response adhere to a supplied JSON Schema, while Microsoft’s documentation distinguishes schema adherence from older JSON mode.
The important distinction is this: valid JSON is not the same as valid data for your application. A parser may accept a JSON object that is missing a required field. A schema gives your code a more precise contract to validate against.
Step 1: Define the result before writing the prompt
Start with the smallest useful object. For an event extractor, the application may need a name, a date, and a list of participants. Make each field explicit and mark every required property. Avoid adding fields that the workflow does not actually use.
from pydantic import BaseModel
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]This model becomes the contract for the response. If you later need a location or an optional note, add it deliberately and update the downstream code at the same time.
Step 2: Ask the model for a parsed structured response
With the current OpenAI Python SDK, the parsing helper can connect a Pydantic model to the Responses API. The model receives the extraction instruction and the source text, while the SDK returns a parsed object that your application can use directly.
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI()
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
response = client.responses.parse(
model="gpt-5.6",
input=[
{"role": "system", "content": "Extract the event information."},
{
"role": "user",
"content": "Alice and Bob are going to a science fair on Friday."
}
],
text_format=CalendarEvent,
)
event = response.output_parsed
print(event.name)
print(event.date)
print(event.participants)The model name in the example is illustrative of the current documentation pattern. Before deploying, confirm that the model available to your account supports Structured Outputs and that your installed SDK version supports the parsing helper.
Step 3: Handle refusals and incomplete inputs
A schema does not make an AI system omniscient. The source text may not contain a date, the request may be unsafe, or the model may refuse to answer. Treat a refusal or missing source fact as a normal application state rather than silently filling the field with a guess.
A practical workflow should therefore perform three checks after the model call:
- Confirm that the response was not refused.
- Confirm that the parsed object contains the fields required by the next step.
- Decide whether missing facts should trigger a retry, a human review state, or a clear “not provided” value.
Step 4: Use enums and nested objects when the workflow needs them
Structured Outputs become especially useful when a workflow has a controlled set of categories. For example, a support classifier might allow only billing, technical, or account. A content workflow might require a fixed status such as draft, review, or ready.
Use constrained values only when they represent real business rules. If the model needs to describe an open-ended idea, a normal string may be safer than an artificially narrow enum.
Step 5: Know when to use function calling instead
Structured response formats are a good fit when you want the model to return data for your application to display or process. Function calling is better when the model needs to request an action, such as looking up a record or creating a task. The two approaches can be part of the same workflow, but they solve different problems.
Keep the action boundary explicit. Let the model propose structured arguments, then let application code enforce permissions, validate values, and decide whether the action is allowed.
A simple reliability checklist
- Define the JSON Schema from the next software step backward.
- Mark required fields and reject unexpected properties where appropriate.
- Handle refusals and missing facts explicitly.
- Validate business rules after schema validation.
- Log the input, schema version, model, and validation outcome for debugging.
- Use a human review state when the cost of a wrong value is high.
Where this helps creators and small teams
You do not need to build a large AI platform to benefit from this pattern. A creator can use a structured schema to turn a video brief into a repeatable checklist. A marketer can extract campaign fields from meeting notes. A site owner can turn tool research into comparable records before writing a review. The key is to define what “complete” means before asking the model to produce the result.
For more practical workflow ideas, see our guides to automating video creation and choosing AI tools for YouTubers.
Sources and further reading
OpenAI’s official guide explains Structured Outputs, JSON Schema adherence, parsing helpers, and the difference between structured response formats and function calling. Microsoft Learn provides a second implementation reference for the Responses API, Chat Completions, Pydantic models, schema limits, and strict function-calling behavior.
Disclosure: This post contains affiliate links. If you purchase through our links, we may earn a commission at no extra cost to you.