Relying on prompts to output valid JSON is a fragile anti-pattern in production. Constrained Decoding forces the model's token-selection logic to align with a formal grammar (like a JSON Schema or Pydantic model). Using frameworks like Instructor, the model is constrained at the engine level to ensure output conforms 100% to your schema, mathematically eliminating malformed JSON.
02 Weak vs. Strong
EX 01Typed Candidate Extraction
from pydantic import BaseModel, Field
import instructor
import openai
class Candidate(BaseModel):
name: str = Field(description="Full name")
skills: list[str] = Field(description="Key technical skills")
years_experience: int = Field(gt=0, description="Must be positive")
client = instructor.from_openai(openai.OpenAI())
candidate = client.chat.completions.create(
model="gpt-4o-mini",
response_model=Candidate,
messages=[{"role": "user", "content": "Marcus Webb has 6 years Go experience"}]
)
→ Why it works
Enforces type checking and constraints during token generation. If the model outputs a negative integer for experience, Pydantic throws a validation error and Instructor retries.
EX 02Structured Application Log Parser
from pydantic import BaseModel, Field, field_validator
import instructor
from openai import OpenAI
class LogEntry(BaseModel):
timestamp: str = Field(description="ISO 8601 timestamp")
severity: str = Field(description="INFO, WARNING, or ERROR")
component: str = Field(description="Service component name")
message: str = Field(description="Sanitised message")
@field_validator('severity')
def validate_severity(cls, v):
if v not in ['INFO', 'WARNING', 'ERROR']:
raise ValueError("Severity must be INFO, WARNING, or ERROR")
return v
client = instructor.from_openai(OpenAI())
log_data = client.chat.completions.create(
model="gpt-4o-mini",
response_model=LogEntry,
messages=[{"role": "user", "content": "[2026-07-06T15:04:12Z] [ERROR] payment-api: Connection pool saturated"}]
)
→ Why it works
Using Pydantic validators ensures that structural correctness is paired with semantic verification. Bad severity strings trigger automatic local correction retries.
03 Key Points
01Token-level filtering: invalid tokens are literally blocked from being generated.
02Instructor wraps LLM clients to bind outputs to typed Pydantic models in Python/JS.
03Syntax guarantee: eliminates the need for 'must output JSON' system rules or regex repair scripts.
04Semantic validation: use Pydantic field validators to check values (e.g. emails, ranges) during generation.
05Retry loops: automatically feeds validation errors back to the model for correction.
04 Model-Specific Notes
Claude supports JSON Mode and Tool Calling, which Instructor uses to enforce schemas. Ensure descriptions on Pydantic fields are detailed since Claude reads them as tool definitions.
05 For Your Role
It's like filling out a digital form with required fields. The form won't let you submit (generate) unless all fields are correctly formatted.