Structured Outputs Strict Mode

Strict Structured Outputs Protocol (Grammar-Constrained Decoding)

Overview

When asking an LLM for structured JSON output, relying purely on prompt instructions ("Return valid JSON matching this schema") results in schema drift: the model occasionally encloses JSON in markdown code blocks (```json), misses required keys, adds unrequested fields, or outputs invalid data types.

When downstream parsers fail, agents are forced into Error Retry Turns, wasting thousands of tokens and stalling workflows.

Strict Structured Outputs (strict: true) uses Context-Free Grammar (CFG) Constrained Decoding: the API converts the provided JSON Schema into a grammar mask at the transformer sampler layer. Any token that would violate the schema is mathematically masked out during generation - guaranteeing 100% schema adherence with zero markdown wrapper tags.

Prompt-Based JSON vs. Strict Grammar Constrained Decoding

┌─────────────────────────────────────────────────────────────┐
│                 JSON Generation Reliability                 │
│                                                             │
│  Prompt-Based JSON (Anti-Pattern - 15% Parse Failures):     │
│  "Here is the JSON you requested:"                          │
│  ```json                                                    │
│  { "user_id": "101", "role": "admin" }                      │
│  ```                                                        │
│  ↳ Markdown code fences require regex stripping             │
│  ↳ Fails if field `role` drifts into `user_role`            │
│                                                             │
│  Strict Structured Outputs (`strict: true` - 100% Exact):   │
│  {"user_id":101,"role":"admin"}                             │
│  ↳ 0 Markdown wrappers, 100% Type-Safe Pydantic Deserialization│
│  ↳ 0 JSON parsing retry turns required                      │
└─────────────────────────────────────────────────────────────┘

Production Python Pydantic Implementation (strict: True)

Using OpenAI's native Pydantic parser integration:

from pydantic import BaseModel, Field
from openai import OpenAI
from typing import List, Literal

client = OpenAI()

class SecurityVulnerability(BaseModel):
    file_path: str = Field(description="Relative path to file")
    line_number: int
    severity: Literal["LOW", "MEDIUM", "HIGH", "CRITICAL"]
    description: str

class AuditReport(BaseModel):
    is_safe: bool
    vulnerabilities: List[SecurityVulnerability]

def run_strict_security_audit(code_snippet: str) -> AuditReport:
    """Executes security audit with 100% mathematically guaranteed schema adherence."""
    completion = client.beta.chat.completions.parse(
        model="gpt-4o-2024-08-06",
        messages=[
            {
                "role": "system",
                "content": "You are a deterministic security auditor. Audit the provided code."
            },
            {"role": "user", "content": code_snippet}
        ],
        response_format=AuditReport, # Automatically compiles to strict JSON Schema
        temperature=0.0
    )
    
    # Returns 100% validated Pydantic model directly
    return completion.choices[0].message.parsed

Production TypeScript / Zod Implementation

import { OpenAI } from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const client = new OpenAI();

const RouteExtractionSchema = z.object({
  endpoint: z.string(),
  method: z.enum(["GET", "POST", "PUT", "DELETE"]),
  authRequired: z.boolean(),
  rateLimitRps: z.number(),
});

export async function extractRouteConfig(rawText: string) {
  const response = await client.chat.completions.create({
    model: "gpt-4o-2024-08-06",
    messages: [
      { role: "system", content: "Extract route configurations." },
      { role: "user", content: rawText },
    ],
    response_format: zodResponseFormat(RouteExtractionSchema, "route_extraction"),
  });

  return JSON.parse(response.choices[0].message.content!);
}

The 3 Rules of Strict Schema Construction

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. ALL FIELDS MUST BE REQUIRED: `strict: true` requires all object keys   │
│    to be listed in the `required: [...]` array (use `null` union for opts)│
│                                                                           │
│ 2. `additionalProperties: false` MUST BE SET: Prevents hallucinated keys  │
│                                                                           │
│ 3. USE `Literal` / `z.enum` FOR FINITE VALUES: Constrains string outputs │
└───────────────────────────────────────────────────────────────────────────┘

Benchmark Comparison

Running 1,000 automated schema extraction jobs in a production pipeline:

Agent Operational Directive

MANDATORY: Whenever structured data extraction or tool argument generation is required, agents must enable strict: true via Pydantic or Zod schemas. Never rely on natural language prompt instructions for JSON validation when grammar-constrained decoding is available.