Union Types and Discriminated Unions
What you'll learn: How to handle LLM responses that can vary in structure using union types and discriminated unions for flexible, validated output.
The Core Idea
Sometimes your LLM needs to return different types of responses depending on the situation. For example, a chatbot might return either a text answer, a list of options, or an error message. Union types let you define "this field can be Type A or Type B," while discriminated unions add a special tag field that explicitly identifies which type you're dealing with.
Think of it like a restaurant menu with sections: the waiter brings you either an appetizer, main course, or dessert. A discriminated union would be like each dish coming with a colored flag — red for appetizer, blue for main, yellow for dessert — so you immediately know what category it belongs to.
Union Types in Pydantic
from pydantic import BaseModel
from typing import Union
class TextResponse(BaseModel):
content: str
class OptionsResponse(BaseModel):
choices: list[str]
class ChatbotOutput(BaseModel):
response: Union[TextResponse, OptionsResponse]
Discriminated Unions
Better yet, add a type field to distinguish variants explicitly:
from typing import Literal
class TextResponse(BaseModel):
type: Literal["text"]
content: str
class OptionsResponse(BaseModel):
type: Literal["options"]
choices: list[str]
class ChatbotOutput(BaseModel):
response: Union[TextResponse, OptionsResponse]
Now Pydantic uses the type field to parse correctly, and your code can check response.type to handle each case appropriately.
Why This Matters
LLMs often need flexibility — returning different structures based on user intent or context. Union types give you type-safe validation for multiple possibilities without rigid constraints.
Key Takeaway: Union types and discriminated unions let you validate flexible LLM outputs with multiple possible structures, using a type field to cleanly distinguish between variants.