Structured Output Contracts (Pydantic, TypeScript, Strict JSON)

The Fragile Bridge: When Natural Language Meets Hard Code

Every software developer who started building with LLMs experienced the same heartbreak: you ask the model for JSON, write JSON.parse(response) in your production backend, and 98% of the time it works smoothly. But on the 99th request, the model decides to write: "Certainly! Here is your requested JSON:" before the brackets, or leaves a trailing comma after the last item. Your server throws a SyntaxError: Unexpected token, and the app crashes.

In enterprise software, 98% reliability is a failing grade. To build resilient software on top of probabilistic models, we need Structured Output Contracts.

From Prompt Hopes to Constrained Decoding

Historically, developers begged the model in the prompt: "Return ONLY valid JSON. No markdown backticks. No conversational filler." Today, modern AI providers (OpenAI, Anthropic, Google Gemini) solve this at the logit generation layer using Constrained Decoding (or Grammar-Based Sampling).

The Modern Stack: Pydantic (Python) & Zod (TypeScript)

Instead of manually hand-crafting complex JSON Schema files, developers define their output contracts using native programming language constructs:

# Python: Defining a Strict Contract with Pydantic
from pydantic import BaseModel, Field
from typing import List, Literal

class RiskItem(BaseModel):
    category: Literal["financial", "operational", "legal", "security"]
    severity: Literal["low", "medium", "high", "critical"]
    description: str = Field(description="Max 25-word summary of the exposure")
    mitigation_strategy: str

class ContractAuditReport(BaseModel):
    vendor_name: str
    effective_date: str
    total_liability_cap_usd: float
    identified_risks: List[RiskItem]
    approved_for_signing: bool

The Golden Rules of Strict Output Contracts

• Set strict: true (or equivalent): Always enable strict schema enforcement in your API client. This instructs the engine to reject non-conformant token paths.
• No Optional Fields Without Explicit Nullability: In strict mode, every property defined in the schema must either be marked as required or explicitly accept None/null as a union type.
• Enforce Categorical Invariants with Enums: Never let the model write freeform strings for statuses. Restrict values to explicit sets like Literal["pending", "completed", "failed"].