AI
Asking a model to "return JSON" and then hoping the output parses is a common source of production bugs — under the right (or wrong) conditions, the model adds a trailing comment, wraps the JSON in markdown fences, or drops a required field. Structured output schema forcing sidesteps the guessing by constraining which tokens the model is allowed to generate at each step, so the result is valid against your schema by construction rather than by luck.
Step-by-Step Implementation
1. Define Schema Model: Create a validation class declaring the required keys, data types, and field descriptions.
2. Configure API Call: Pass the schema model directly to the client's completion parameters.
3. Extract Parsed Object: Process the validated result directly as an object, eliminating manual regex parsing steps.
# Enforce structured JSON schema matching via Pydantic
from pydantic import BaseModel, Field
from openai import OpenAI
class LearningPlan(BaseModel):
topic: str = Field(description="The primary concept being taught")
difficulty: str = Field(description="Beginner, Intermediate, or Professional")
subsections: list[str] = Field(description="List of 3 subtopics to learn")
estimated_hours: float = Field(description="Hours required to complete")
client = OpenAI()
def generate_structured_lesson(topic_query: str):
completion = client.beta.chat.completions.parse(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "You are an educational assistant. Output matching the schema."},
{"role": "user", "content": f"Create a guide for: {topic_query}"}
],
response_format=LearningPlan
)
return completion.choices[0].message.parsed| Prompt Design | Parsing Exception Rate | Efficacy Constraint |
|---|---|---|
| Raw text constraints | High (~5-15% format deviations) | Low (Model easily deviates under context load) |
| Structured JSON Schema forcing | 0% (Guaranteed schema alignment) | High (Model outputs are strictly token-masked) |
The Pydantic model doubles as documentation for what your pipeline actually expects, which is worth as much as the parsing guarantee — a downstream engineer can read the schema and know exactly what fields exist without reading the prompt.
Practical Challenge
Define a Pydantic model for a cooking recipe containing fields for name, prep_time, ingredients (list of dicts with name and amount), and instructions (list of strings).
Concept Check
Sources & Further Reading
- Pydantic Documentation — the validation library used to define the schema in the code sample above.
- OpenAI — Structured Outputs guide — how `response_format`/schema forcing works at the API level.