Course contentsShow
← AI Engineering
Lesson 775 of 1,88619. Structured Output and ValidationFree lesson

Union Types and Discriminated Unions

Handle multiple possible output formats with union types and discriminated unions for flexible LLM responses.

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.