Skip to main content

Union Types

Union types can hold one of several specified types.

Syntax​

Type1 | Type2
Type1 | Type2 | Type3

Examples​

Basic Unions​

int | string
string | MyClass
int | string | bool

Complex Unions​

(int | string) | MyClass
string | MyClass | int[]
int? | string[] | MyClass

Usage​

Function Return Types​

function ClassifyIssue(description: string) -> "bug" | "enhancement" {
    client "openai/gpt-4o"
    prompt #"
        Classify the issue:
        {{ ctx.output_format }}

        {{ _.role("user") }}
        {{ description }}
    "#
}

Function Calling​

Unions are useful for function calling where you want to return different types depending on which function should be called:

class SearchAction {
    query string
}

class NavigateAction {
    url string
}

function DetermineAction(input: string) -> SearchAction | NavigateAction {
    client "openai/gpt-4o"
    prompt #"
        Determine the user's intent:
        {{ ctx.output_format }}

        {{ _.role("user") }}
        {{ input }}
    "#
}

Order Matters​

warning

The order of types in a union affects parsing behavior.

For example, if the LLM returns "1":

  • int | string - parses as int (value: 1)
  • string | int - parses as string (value: "1")

BAML attempts to parse in left-to-right order, using the first type that successfully parses.

Language Equivalents​

BAMLPythonTypeScriptGo
int | stringUnion[int, str]number | stringUnion2IntOrString
int? | string[]Union[Optional[int], List[str]](number | null) | string[]Union2IntOrStringArray
"a" | "b" | 1Union[Literal["a"], Literal["b"], Literal[1]]"a" | "b" | 1Union3StringOrStringOrInt

See Also​