Array Types

Working with collections and lists in BAML

Arrays allow you to store and manipulate collections of data. They can be declared in both single-line and multi-line formats.

Syntax

Type[] · array

A collection of elements of the same type

Type[]           // Basic array
(int | string)[] // Array of unions
int[][]          // Multi-dimensional array

Declaration Syntax

Arrays can be declared inline or across multiple lines:

{
  key1 [value1, value2, value3],
  key2 [
    value1,
    value2,
    value3
  ],
  key3 [
    {
      subkey1 "valueA",
      subkey2 "valueB"
    },
    {
      subkey1 "valueC",
      subkey2 "valueD"
    }
  ]
}

Key Points:

• Commas are optional for multi-line arrays but recommended for clarity
• Nested arrays are supported for complex data structures
• Arrays can contain objects with key-value pairs

Basic Array Example

function DescriptionGame(items: string[]) -> string {
    client "openai/gpt-4o-mini"
    prompt #"
        What 3 words best describe all of these: {{ items }}.
    "#
}

test FruitList {
    functions [DescriptionGame]
    args { items ["apple", "banana", "cherry"] }
}

Generated Types

Python

from typing import List

items: List[str] = ["apple", "banana", "cherry"]

Multi-line Arrays

For better readability, arrays can span multiple lines:

test CityDescription {
    functions [DescriptionGame]
    args { items [
            "New York",
            "Los Angeles",
            "Chicago"
        ]
    }
}

Arrays of Complex Types

Arrays of Classes

class Person {
    name string
    age int
}

function AnalyzePeople(people: Person[]) -> string {
    client "openai/gpt-4o-mini"
    prompt #"
        Analyze these people: {{ people }}
    "#
}

test PeopleAnalysis {
    functions [AnalyzePeople]
    args {
        people [
            { name "Alice", age 30 },
            { name "Bob", age 25 }
        ]
    }
}

Generated Types

Python

from typing import List
from baml_client.types import Person

people: List[Person] = [
    Person(name="Alice", age=30),
    Person(name="Bob", age=25)
]

Union Arrays

Arrays can contain union types:

function ProcessMixed(data: (int | string)[]) -> string {
    client "openai/gpt-4o-mini"
    prompt #"
        Process this mixed data: {{ data }}
    "#
}

test MixedData {
    functions [ProcessMixed]
    args { data [1, "hello", 42, "world"] }
}

Generated Types

Python

from typing import List, Union

data: List[Union[int, str]] = [1, "hello", 42, "world"]

Multi-dimensional Arrays

Nested arrays for matrix-like data:

function AnalyzeMatrix(matrix: int[][]) -> string {
    client "openai/gpt-4o-mini"
    prompt #"
        Analyze this matrix: {{ matrix }}
    "#
}

test MatrixAnalysis {
    functions [AnalyzeMatrix]
    args {
        matrix [
            [1, 2, 3],
            [4, 5, 6],
            [7, 8, 9]
        ]
    }
}

Generated Types

Python

from typing import List

matrix: List[List[int]] = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]

Optional Arrays

Arrays can be optional:

function ProcessOptionalList(items: string[]?) -> string {
    client "openai/gpt-4o-mini"
    prompt #"
        {% if items %}
        Process these items: {{ items }}
        {% else %}
        No items provided.
        {% endif %}
    "#
}

Generated Types

Python

from typing import List, Optional

items: Optional[List[str]] = None
# or
items: Optional[List[str]] = ["item1", "item2"]

Arrays of Enums

enum Color {
    Red
    Green
    Blue
}

function AnalyzeColors(colors: Color[]) -> string {
    client "openai/gpt-4o-mini"
    prompt #"
        Analyze these colors: {{ colors }}
    "#
}

test ColorAnalysis {
    functions [AnalyzeColors]
    args { colors [Red, Green, Blue] }
}

Generated Types

Python

from typing import List
from enum import StrEnum

class Color(StrEnum):
    Red = "Red"
    Green = "Green"
    Blue = "Blue"

colors: List[Color] = [Color.Red, Color.Green, Color.Blue]

Constraints and Validation

Important Constraints:

• Array types cannot be optional themselves (use Type[]? instead of Type?[])
• Arrays can be nested to create multi-dimensional structures
• All elements must be of the same type (or match the union type)

Best Practices

1. Use multi-line format for arrays with more than 3 elements for better readability
2. Include trailing commas in multi-line arrays for easier editing
3. Use descriptive variable names that indicate the array contains multiple items
4. Consider using classes for arrays of complex structured data