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.
1. Why plain text becomes a problem
Section titled “1. Why plain text becomes a problem”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 ITto:
PYTHON DEFINES ALLOWED SHAPE ↓MODEL FILLS THAT SHAPE ↓PYTHON READS KNOWN FIELDSThat’s a major architectural improvement.
3. Define the contract in Python
Section titled “3. Define the contract in Python”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: boolThis class is doing more than describing some data.
It is saying:
Any valid
NextStepmust contain these three fields with these types.
Conceptually:
NextStep│├── action string├── reason string└── requires_human booleanThis 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.
4. Ask the model to satisfy the contract
Section titled “4. Ask the model to satisfy the contract”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 OpenAIfrom 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=NextStepWe’re not merely saying in English:
Please return JSON.We’re giving the API an actual structure.
And:
response.output_parsedgives 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.
5. What result actually is
Section titled “5. What result actually is”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_parsedmeans 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_documentAnd:
print(result.requires_human)Output:
FalseNo JSON parsing code.
No string matching.
No searching through paragraphs.
6. Why Pydantic is especially useful here
Section titled “6. Why Pydantic is especially useful here”If you’ve used FastAPI, you may have seen the same kind of declaration at an HTTP boundary:
class UserCreate(BaseModel): email: str name: strThe 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 ↓applicationWith FastAPI:
BROWSER ↓arbitrary request data ↓Pydantic contract ↓applicationSame idea.
You’re controlling the boundary where uncertain external data enters your program.
7. We can make the contract stronger
Section titled “7. We can make the contract stronger”Our current model says:
action: strThat means these are all structurally valid:
analyze_documentsend_emaillaunch_nuclear_submarineThey’re strings.
But perhaps our software only permits three possible decisions.
That’s a perfect job for an enum.
from enum import Enumfrom 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: boolNow our contract says:
action MUST be one of:
analyze_documentrequest_reviewdo_nothingThat’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_databasesend_emailcreate_reportrequest_human_approvalfinishYou don’t want the model inventing:
probably_email_the_customeror:
contact_userYour 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.
9. Notice what we are NOT doing yet
Section titled “9. Notice what we are NOT doing yet”We still have not given the model the ability to perform anything.
This:
result.actionmight equal:
analyze_documentBut the document has not been analyzed.
We only received a structured decision.
Conceptually:
MODEL ↓{ action: analyze_document} ↓PYTHONPython 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.
10. Structure does not mean correctness
Section titled “10. Structure does not mean correctness”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 CORRECTNESS11. 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 JSONbut arbitrary structurefrom:
STRUCTURED OUTPUT
valid structurematching your declared schema12. 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: strThat’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: strNow 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: boolis 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: NextStepAn 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_parsedNow 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 PythonThat 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 Enumfrom pydantic import BaseModel
class SupportAction(str, Enum): ANSWER = "answer" LOOK_UP_ACCOUNT = "look_up_account" ESCALATE = "escalate"
class SupportDecision(BaseModel): action: SupportAction reason: strThen:
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_parsedNow:
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 itWith structure:
Python ↓LLM ↓KNOWN CONTRACT ↓PythonIn 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 finishNotice how much easier that is to reason about.
17. Short exercise
Section titled “17. Short exercise”Imagine you’re designing a model that reviews a user-submitted article before publication.
The model should decide one of three things:
publishrevisehuman_reviewAnd your Python application needs:
decisionshort explanationlist of issuesBefore looking below, mentally design the Pydantic contract.
A perfectly reasonable answer is:
from enum import Enumfrom 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: ArticleReviewThat’s already the beginning of a robust AI component.
What breaks in production?
Section titled “What breaks in production?”Structured Outputs remove one category of chaos.
They do not remove all of it.
1. Valid structure, bad decision
Section titled “1. Valid structure, bad decision”The model returns:
decision=PublicationDecision.PUBLISHbut the article clearly requires review.
The schema worked.
The reasoning didn’t.
This is why eventually we need evals.
2. Your schema is too vague
Section titled “2. Your schema is too vague”class Result(BaseModel): result: strTechnically structured.
Practically useless.
Good structured outputs require good application design.
3. Your schema is too complicated
Section titled “3. Your schema is too complicated”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: strallows too much.
This:
action: Actiondefines 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:
billingtechnicalcancellationand 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.
6. Refusals or incomplete responses
Section titled “6. Refusals or incomplete responses”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.
The deeper lesson
Section titled “The deeper lesson”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 SOFTWAREThis 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.
Keep this distinction
Section titled “Keep this distinction”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.