structured-outputs

name	structured-outputs
description	Techniques for ensuring LLM responses adhere to strict JSON schemas, utilizing Pydantic models, JSON mode, and schema-based refusals. Triggers: structured-output, pydantic, json-schema, json-mode, llm-response-parsing.

Structured Outputs

Overview

Structured Outputs ensure that an LLM's response always conforms to a predefined JSON schema. This moves beyond simple prompt engineering to guaranteed syntactic and structural correctness, essential for programmatic integration.

When to Use

• API Integration: When LLM output must be parsed by a machine (e.g., generating database records).
• UI Components: When the LLM generates data to populate a specific frontend interface.
• Data Extraction: Converting unstructured text into standardized JSON objects.

Decision Tree

1. Do you need 100% guarantee of schema adherence?
   • YES: Use Structured Output mode (e.g., OpenAI's strict: true or Gemini's response_mime_type).
   • NO: JSON Mode may suffice.
2. Is the structure complex or nested?
   • YES: Use Pydantic models and model_rebuild if recursive.
3. Do you need to handle safety refusals programmatically?
   • YES: Check for the refusal field in the response.

Workflows

1. Defining a Pydantic-based Schema

1. Define a Python class inheriting from BaseModel.
2. Use specific types (e.g., int, List[str]) and Field descriptions to guide the model.
3. Pass the model directly to the SDK's parse method (e.g., client.beta.chat.completions.parse).