Expression Language

Expressions are enclosed in ${} and evaluated at runtime. They can appear anywhere a value is expected: assignments, conditions, function arguments, URLs, and more.

Syntax

- step:
    assign:
      - result: ${a + b}
      - greeting: '${"Hello, " + name + "!"}'
      - check: ${x > 10 and y < 20}

When an expression starts a YAML value, wrap the entire value in quotes to avoid YAML parsing issues with colons and special characters.

Maximum expression length: 400 characters.

Data types

Operators

Arithmetic

Type promotion: When int and double are mixed, int is promoted to double. Division / always returns double, even ${4 / 2} = 2.0.

No implicit string conversion: ${"count: " + 42} is a TypeError. Use ${"count: " + string(42)}.

Comparison

• null == null is true
• null == <anything_else> is false
• Comparing incompatible types with <, >, <=, >= raises TypeError
• == and != between incompatible types returns false (no error)
• Maps and lists use deep equality

Logical

Operands must be boolean. not "hello" or true and 1 raises TypeError. Short-circuit: if the left operand determines the result, the right operand is not evaluated.

Membership

Property and index access

• Missing map key raises KeyError
• Out-of-bounds list index raises IndexError
• Negative list indices are not supported (raises IndexError)
• Use map.get(obj, "key", default) for safe access

Operator precedence

From highest to lowest:

1. ., [] -- property/index access
2. not, - (unary) -- negation
3. *, /, %, // -- multiplicative
4. +, - -- additive
5. <, >, <=, >= -- relational
6. ==, != -- equality
7. in, not in -- membership
8. and -- logical AND
9. or -- logical OR

Use parentheses () to override precedence.

Function calls in expressions

Built-in functions and standard library functions can be called inside ${}:

- step:
    assign:
      - count: ${len(items)}
      - upper_name: ${text.to_upper(name)}
      - safe_value: ${default(map.get(config, "key"), "fallback")}
      - data_type: ${type(value)}
      - id: ${uuid.generate()}

Subworkflows can also be called with positional arguments:

- step:
    assign:
      - result: ${my_subworkflow("arg1", "arg2")}

See the Standard Library for all available functions.

Null handling

# Accessing a missing map key raises KeyError -- NOT null
- bad: ${myMap.missingKey}              # KeyError!

# Safe access with map.get (returns null if not found)
- safe: ${map.get(myMap, "key")}        # null if missing

# Safe access with a default value
- safe: ${map.get(myMap, "key", 0)}     # 0 if missing

# default() handles null but does NOT catch KeyError
- val: ${default(map.get(myMap, "key"), "fallback")}

# Null comparisons
- is_null: ${value == null}             # true if value is null
- both_null: ${null == null}            # true

Common patterns

String building

- step:
    assign:
      - url: '${"http://localhost:9090/users/" + string(user_id) + "/orders"}'
      - message: '${"Found " + string(len(items)) + " items"}'

Conditional defaults

- step:
    assign:
      - timeout: ${default(map.get(config, "timeout"), 30)}
      - name: ${default(map.get(args, "name"), "Anonymous")}

Type checking

- step:
    switch:
      - condition: ${type(value) == "list"}
        assign:
          - count: ${len(value)}
      - condition: ${type(value) == "string"}
        assign:
          - count: 1

Checking for map keys

- step:
    switch:
      - condition: ${"email" in user}
        next: send_email
      - condition: true
        next: skip_notification

Edge cases