Skip to content

02 · Structured Outputs as Contracts

In Lesson 1, we ended with a problem.

The model might decide that the next action is:

Analyze the PDF.

Or:

Begin document analysis.

Or:

The document should now be sent for analysis.

A human understands that all three mean roughly the same thing.

Python does not.

Today we’re going to fix that.

The core idea is:

When model output will drive software behavior, don’t ask for prose. Ask for a contract.

That contract is a predefined structure your Python code can rely on.


Suppose our program asks:

response = client.responses.create(
model="gpt-5.5-2026-04-23",
input="""
A PDF has passed validation but has not been analyzed.
What should happen next?
"""
)
print(response.output_text)

Maybe we get:

Analyze the PDF.

You could write:

if response.output_text == "Analyze the PDF.":
analyze_document()

But this is extremely fragile.

The model could instead return:

The next step is to analyze the PDF.

Now:

response.output_text == "Analyze the PDF."

is False.

Nothing is wrong with the model’s answer.

The problem is our interface between the model and Python.


2. Humans want meaning. Programs want structure.

Section titled “2. Humans want meaning. Programs want structure.”

Humans are comfortable with:

Looks like this document needs analysis.

Programs prefer:

{
"action": "analyze_document"
}

Better still:

{
"action": "analyze_document",
"reason": "The document passed validation and has not been analyzed.",
"requires_human": False
}

Now Python doesn’t need to interpret English.

It can do:

if result.action == "analyze_document":
...

We have moved from:

MODEL WRITES SOMETHING
↓
PYTHON TRIES TO UNDERSTAND IT

to:

PYTHON DEFINES ALLOWED SHAPE
↓
MODEL FILLS THAT SHAPE
↓
PYTHON READS KNOWN FIELDS

That’s a major architectural improvement.


Pydantic is a Python data-validation library. A class derived from BaseModel declares named fields and their types. The SDK can use that declaration to build the model’s output schema and parse a matching result. You do not need to know FastAPI to follow this example.

Let’s define the answer we expect.

from pydantic import BaseModel
class NextStep(BaseModel):
action: str
reason: str
requires_human: bool

This class is doing more than describing some data.

It is saying:

Any valid NextStep must contain these three fields with these types.

Conceptually:

NextStep
│
├── action string
├── reason string
└── requires_human boolean

This is our contract.

requires_human is still the model’s proposal. A value of False cannot switch off an approval rule enforced by Python. Lesson 7 keeps that policy in the application.


The current Python SDK can take a Pydantic model directly, convert it into the schema sent to the model, and parse a matching response back into a typed Python object. OpenAI Developers

from openai import OpenAI
from pydantic import BaseModel
client = OpenAI()
class NextStep(BaseModel):
action: str
reason: str
requires_human: bool
response = client.responses.parse(
model="gpt-5.5-2026-04-23",
instructions="""
Decide the single next action for the software system.
""",
input="""
A user uploaded a PDF.
The PDF passed validation.
The document has not yet been analyzed.
""",
text_format=NextStep,
)
if response.status != "completed" or response.output_parsed is None:
raise RuntimeError("No completed structured result returned.")
result = response.output_parsed
print(result)

The important part is:

text_format=NextStep

We’re not merely saying in English:

Please return JSON.

We’re giving the API an actual structure.

And:

response.output_parsed

gives us the parsed object when one is available. The preceding check stops this example if the response is incomplete or no parsed result exists, including a refusal. SDK parsing or network errors can also raise exceptions; a declared return type does not remove those failure paths.


Assume the model produces the equivalent of:

{
"action": "analyze_document",
"reason": "The document is valid and has not yet been analyzed.",
"requires_human": false
}

Then:

result = response.output_parsed

means result is essentially:

NextStep(
action="analyze_document",
reason="The document is valid and has not yet been analyzed.",
requires_human=False,
)

So you can use normal Python:

print(result.action)

Output:

analyze_document

And:

print(result.requires_human)

Output:

False

No JSON parsing code.

No string matching.

No searching through paragraphs.


If you’ve used FastAPI, you may have seen the same kind of declaration at an HTTP boundary:

class UserCreate(BaseModel):
email: str
name: str

The purpose is very similar.

A browser might send arbitrary JSON.

Your FastAPI application says:

For this endpoint, I expect data shaped like UserCreate.

With an LLM:

MODEL
↓
arbitrary possible output
↓
Pydantic contract
↓
application

With FastAPI:

BROWSER
↓
arbitrary request data
↓
Pydantic contract
↓
application

Same idea.

You’re controlling the boundary where uncertain external data enters your program.


Our current model says:

action: str

That means these are all structurally valid:

analyze_document
send_email
launch_nuclear_submarine

They’re strings.

But perhaps our software only permits three possible decisions.

That’s a perfect job for an enum.

from enum import Enum
from pydantic import BaseModel
class Action(str, Enum):
ANALYZE_DOCUMENT = "analyze_document"
REQUEST_REVIEW = "request_review"
DO_NOTHING = "do_nothing"
class NextStep(BaseModel):
action: Action
reason: str
requires_human: bool

Now our contract says:

action MUST be one of:
analyze_document
request_review
do_nothing

That’s much stronger.


8. Why enums matter enormously in agent systems

Section titled “8. Why enums matter enormously in agent systems”

Imagine eventually giving an agent these capabilities:

search_database
send_email
create_report
request_human_approval
finish

You don’t want the model inventing:

probably_email_the_customer

or:

contact_user

Your software doesn’t have those operations.

The model must choose from the vocabulary your application understands.

That’s one reason structured outputs are foundational for agent engineering.

Instead of:

Model:
"I think perhaps you should send them an email."

you want:

Decision(
action=Action.SEND_EMAIL,
...
)

Now Python can reason about it safely.


We still have not given the model the ability to perform anything.

This:

result.action

might equal:

analyze_document

But the document has not been analyzed.

We only received a structured decision.

Conceptually:

MODEL
↓
{
action: analyze_document
}
↓
PYTHON

Python still has to decide what to do with that information.

For example:

if result.action == Action.ANALYZE_DOCUMENT:
print("Python would now start document analysis.")

Tomorrow’s lesson—tool/function calling—is where we begin connecting a model’s decision to actual Python capabilities.


This is one of the most important distinctions in the lesson.

Suppose the model returns:

{
"action": "do_nothing",
"reason": "The document has already been analyzed.",
"requires_human": false
}

Our schema may be perfectly valid.

But what if the document has not been analyzed?

The structure is correct.

The reasoning is wrong.

Structured Outputs solve:

Did the model return data shaped correctly?

They do not solve:

Did the model make the right decision?

OpenAI’s documentation explicitly makes this distinction: Structured Outputs ensure schema adherence, but the values inside that schema can still contain mistakes. OpenAI Developers

This distinction matters enormously.

Think:

STRUCTURAL CORRECTNESS
≠
SEMANTIC CORRECTNESS

11. JSON is not the same thing as Structured Outputs

Section titled “11. JSON is not the same thing as Structured Outputs”

You will see plenty of code like:

instructions="""
Return JSON like this:
{
"action": "...",
"reason": "..."
}
"""

That’s better than unconstrained prose.

But it’s still relying primarily on prompting.

The model might produce:

Sure! Here's the JSON:
{
...
}

Or forget a field.

Or use another value.

There’s also JSON mode, which ensures syntactically valid JSON.

But valid JSON is still not necessarily the shape your application expects.

For example, this is perfectly valid JSON:

{
"banana": 17
}

Not very helpful if you expected:

{
"action": "analyze_document",
"requires_human": false
}

Current OpenAI guidance recommends Structured Outputs instead of JSON mode where possible because Structured Outputs enforce the schema, not merely valid JSON syntax. OpenAI Developers

So mentally distinguish:

PLAIN TEXT
"Analyze the document."

from:

JSON MODE
valid JSON
but arbitrary structure

from:

STRUCTURED OUTPUT
valid structure
matching your declared schema

12. The contract should reflect what your program actually needs

Section titled “12. The contract should reflect what your program actually needs”

This is a subtle design skill.

You could create:

class Decision(BaseModel):
complete_analysis_of_everything: str

That’s useless.

Or:

class Decision(BaseModel):
action: Action
confidence: float
reason: str
full_reasoning: str
alternative_actions: list[str]
long_term_strategy: str
risk_analysis: str
emotional_state: str

Now we’re probably overdoing it.

Ask:

What information does my Python application actually need in order to make the next decision?

For our example:

class NextStep(BaseModel):
action: Action
reason: str
requires_human: bool

is probably enough.

That is good interface design.


13. Think of the model as a strange function

Section titled “13. Think of the model as a strange function”

Normal Python:

def choose_action(document_status: str) -> NextStep:
...

You would expect:

INPUT:
document_status
OUTPUT:
NextStep

An LLM-backed function can be designed the same way:

def choose_action(context: str) -> NextStep:
response = client.responses.parse(
model="gpt-5.5-2026-04-23",
instructions="Choose the next action.",
input=context,
text_format=NextStep,
)
if response.status != "completed" or response.output_parsed is None:
raise RuntimeError("No completed structured result returned.")
return response.output_parsed

Now the rest of your application doesn’t need to know very much about the LLM.

It sees:

decision = choose_action(context)
if decision.action == Action.ANALYZE_DOCUMENT:
...

Architecturally:

fuzzy natural language
↓
┌─────────────┐
│ LLM │
└──────┬──────┘
↓
NextStep object
↓
deterministic Python

That boundary is extremely valuable.


14. Let’s make the example more realistic

Section titled “14. Let’s make the example more realistic”

Imagine a customer support system.

We want the model to classify an incoming message.

from enum import Enum
from pydantic import BaseModel
class SupportAction(str, Enum):
ANSWER = "answer"
LOOK_UP_ACCOUNT = "look_up_account"
ESCALATE = "escalate"
class SupportDecision(BaseModel):
action: SupportAction
reason: str

Then:

def decide_support_action(message: str) -> SupportDecision:
response = client.responses.parse(
model="gpt-5.5-2026-04-23",
instructions="""
Decide what the support system should do next.
Choose:
- answer: general information is sufficient
- look_up_account: account-specific information is required
- escalate: a human should handle the request
""",
input=message,
text_format=SupportDecision,
)
if response.status != "completed" or response.output_parsed is None:
raise RuntimeError("No completed structured result returned.")
return response.output_parsed

Now:

decision = decide_support_action(
"Why was I charged twice this month?"
)

Maybe:

SupportDecision(
action=SupportAction.LOOK_UP_ACCOUNT,
reason="Answering requires checking the customer's billing history.",
)

Then ordinary Python:

if decision.action == SupportAction.LOOK_UP_ACCOUNT:
print("Need account data.")

We’re starting to see an agent architecture appear.


15. Where should deterministic logic stay deterministic?

Section titled “15. Where should deterministic logic stay deterministic?”

This is especially important.

Suppose you already know:

if document.file_size > 10_000_000:
reject_file()

Don’t ask the model:

The file is 12 MB and the maximum is 10 MB.
Should we reject it?

That’s absurd.

Python already knows the answer.

Use deterministic code for deterministic rules:

MAX_FILE_SIZE = 10_000_000
if document.file_size > MAX_FILE_SIZE:
reject_file()

Use the LLM when judgment or language understanding is actually valuable.

For example:

Does this user's message sound like a billing question,
technical support issue, or cancellation request?

Then return:

class Category(str, Enum):
BILLING = "billing"
TECHNICAL = "technical"
CANCELLATION = "cancellation"

This separation is going to matter throughout the series.


16. A useful mental model: the model sits inside a typed boundary

Section titled “16. A useful mental model: the model sits inside a typed boundary”

Without structure:

Python
↓
LLM
↓
??????
↓
Python somehow handles it

With structure:

Python
↓
LLM
↓
KNOWN CONTRACT
↓
Python

In pseudocode:

SEND context to model
EXPECT:
action
reason
requires_human
RECEIVE structured decision
IF action == analyze_document
continue workflow
IF action == request_review
stop for human review
IF action == do_nothing
finish

Notice how much easier that is to reason about.


Imagine you’re designing a model that reviews a user-submitted article before publication.

The model should decide one of three things:

publish
revise
human_review

And your Python application needs:

decision
short explanation
list of issues

Before looking below, mentally design the Pydantic contract.

A perfectly reasonable answer is:

from enum import Enum
from pydantic import BaseModel
class PublicationDecision(str, Enum):
PUBLISH = "publish"
REVISE = "revise"
HUMAN_REVIEW = "human_review"
class ArticleReview(BaseModel):
decision: PublicationDecision
explanation: str
issues: list[str]

That’s it.

You don’t need an agent framework.

You don’t need a “critic agent.”

You don’t need a workflow engine.

You have simply defined:

INPUT:
article
OUTPUT:
ArticleReview

That’s already the beginning of a robust AI component.


Structured Outputs remove one category of chaos.

They do not remove all of it.

The model returns:

decision=PublicationDecision.PUBLISH

but the article clearly requires review.

The schema worked.

The reasoning didn’t.

This is why eventually we need evals.


class Result(BaseModel):
result: str

Technically structured.

Practically useless.

Good structured outputs require good application design.


A giant deeply nested schema can make both the model interaction and your own application harder to reason about.

Prefer the smallest contract that represents what the next stage genuinely needs.


4. You use strings where enums would be safer

Section titled “4. You use strings where enums would be safer”

This:

action: str

allows too much.

This:

action: Action

defines the permitted vocabulary.

Whenever downstream Python branches on a small known set of possibilities, consider an enum.


5. The request cannot produce a sensible answer

Section titled “5. The request cannot produce a sensible answer”

Suppose your classifier expects:

billing
technical
cancellation

and the user writes:

What's the capital of Italy?

The model still needs a valid schema-compatible response.

Your design should explicitly handle this.

Perhaps:

class Category(str, Enum):
BILLING = "billing"
TECHNICAL = "technical"
CANCELLATION = "cancellation"
UNSUPPORTED = "unsupported"

Your schema design is part of your application logic.


Even with Structured Outputs, production code needs to account for cases such as safety refusals or incomplete responses rather than blindly assuming a parsed result will always exist. The current API documentation specifically calls these out as edge cases. OpenAI Developers

Conceptually:

result = response.output_parsed
if result is None:
# handle failure/refusal/incomplete response
...

We’ll deal with robust failure handling properly in Lesson 6.


Structured Outputs are not primarily about JSON.

They’re about software boundaries.

Instead of letting natural language leak everywhere through your application, you create places where uncertainty gets converted into known data.

NATURAL LANGUAGE / JUDGMENT
↓
LLM
↓
STRUCTURED CONTRACT
↓
DETERMINISTIC SOFTWARE

This is one of the patterns that separates:

"AI demo"

from:

"software system that happens to use AI"

The same boundary idea appears in web applications built with Pydantic and FastAPI:

Pydantic validates the boundary between uncertain outside data and the rest of your program.

With FastAPI, that outside data might come from a browser.

With an AI system, it may come from a model.

Same engineering instinct.


After two lessons, our system looks like this:

CONTEXT
↓
┌─────────┐
│ LLM │
└────┬────┘
↓
STRUCTURED DECISION
↓
┌─────────┐
│ PYTHON │
└─────────┘

The model can now make a decision in a format Python understands.

But Python still can’t give the model actual capabilities.

That changes in Lesson 3: Tool / Function Calling.

We’ll take the next step from:

{
"action": "look_up_account"
}

to the model actually requesting:

look_up_account(customer_id="123")

and we’ll see exactly what happens under the hood when the model chooses a function but Python executes it.