Interpolation

Interpolation constructs a string by combining literal text with evaluated expressions. It provides a concise way to build messages, paths, URLs, identifiers, and other textual values without explicit string concatenation.

An interpolated string contains literal text mixed with one or more ${...} expressions. Each expression is evaluated, converted to text, and concatenated with the surrounding literal text.

---

Syntax

Interpolation expressions are enclosed in ${...}.

${EXPR}

Multiple interpolations may appear within the same string.

"Hello ${first} ${last}!"

"/users/${$.customer.id}/orders/${order}"

"https://api.example.com/${tenant}/${version}"

Text outside ${...} is copied unchanged into the result.

---

Expressions

Interpolation supports the same forms used elsewhere in JFTL.

Variables

Variables can be referenced directly by name:

"Hello ${name}!"

"Customer ${customer_id}"

For example:

{
  "$": true,
  "set": {
    "name": "Alice",
    "customer_id": 12345
  },
  "out": "Customer ${customer_id}: ${name}"
}

Result:

Customer 12345: Alice

Navigation

Navigation expressions can be used to select values from the current data:

"Hello ${$.name}!"

"${$.city}, ${$.country}"

For example, with:

{
  "name": "Alice",
  "address": {
    "city": "London"
  }
}

the interpolation:

"${$.name} lives in ${$.address.city}"

produces:

Alice lives in London

Loop values

Inside foreach, _ can be used to interpolate the current iteration value.

{
  "$": true,
  "foreach": {
    "in": "$.items",
    "out": "Item: ${_}"
  }
}

With:

{
  "items": ["Apple", "Banana", "Orange"]
}

the result is:

[
  "Item: Apple",
  "Item: Banana",
  "Item: Orange"
]

Other iteration variables can be used in the same way where available.

Expressions

General expressions can be evaluated inside interpolation.

"Total: ${py=price * quantity}"

For example:

{
  "$": true,
  "set": {
    "price": 12,
    "quantity": 3
  },
  "out": "Total: ${py=price * quantity}"
}

Result:

Total: 36

---

Escape Sequence

To include the literal text ${ without starting an interpolation, prefix it with an additional $.

$${    →    ${

For example:

{
  "$": true,
  "set": {
    "name": "Alice"
  },
  "out": "Use $${name} to refer to the variable named ${name}."
}

Result:

Use ${name} to refer to the variable named Alice.

---

Value Conversion

Each interpolated expression is converted to text before concatenation.

Value	Result
String	unchanged
Number	decimal representation
Boolean	true or false
null	null
Missing	null

Objects and arrays cannot be interpolated directly. Attempting to do so results in a runtime error.

---

Structured output

Interpolation works naturally alongside ordinary JFTL expressions.

{
  "$": true,
  "set": {
    "first": "Alice",
    "last": "Smith",
    "customer_id": 12345
  },
  "out": {
    "id": "$customer_id",
    "name": "${first} ${last}",
    "display": "Customer ${customer_id}: ${first} ${last}"
  }
}

Result:

{
  "id": 12345,
  "name": "Alice Smith",
  "display": "Customer 12345: Alice Smith"
}

id is produced by an ordinary navigation expression, so it remains an integer. name and display use interpolation and therefore produce strings.

---

Reusing computed values

Interpolation can be used to build intermediate values that are later referenced by ordinary expressions.

Input:

{
  "first": "Alice",
  "last": "Smith",
  "customer_id": 12345
}

Template:

{
  "$": true,
  "set": {
    "full_name": "${$.first} ${$.last}"
  },
  "out": {
    "id": "$.customer_id",
    "name": "$full_name",
    "message": "Welcome ${full_name}!"
  }
}

Result:

{
  "id": 12345,
  "name": "Alice Smith",
  "message": "Welcome Alice Smith!"
}

---

Interpolation vs. ordinary expressions

Interpolation always produces a string.

For example:

{
  "value": "$customer_id",
  "label": "Customer ${customer_id}"
}

If $customer_id is the integer 12345, the result is:

{
  "value": 12345,
  "label": "Customer 12345"
}

Use an ordinary JFTL expression when the result should retain its JSON type. Use interpolation when constructing text.

---

Summary

• Interpolation constructs strings by combining literal text with evaluated expressions.
• Expressions are enclosed in ${...}.
• Multiple interpolations may appear in the same string.
• Variables can be referenced as ${name}.
• Navigation expressions can be used, for example ${$.customer.name}.
• Iteration values can be referenced, for example ${_}.
• General expressions can be evaluated, for example ${py=price * quantity}.
• Use $${ to produce the literal text ${.
• Interpolated values are converted to text before concatenation.
• Interpolation always produces a string.
• Objects and arrays cannot be interpolated directly.

A string is not treated as interpolation when it is already interpreted as another JFTL string form, including:

• navigation expressions such as "$", "$foo", and "$.customer.address";
• expression forms such as "$=..." and "$py=...";
• quoted strings beginning with "$$";
• strings within literal blocks such as { "$": false, "out": ... }.