Expansion

Introduction

Property expansion is the process of replacing a value, or a part of a value, with the result of an expression.

The actual expression is a tag containing a (dot-separated) path to a named property.

Expansion expressions are written in the following format:

"${path.to.property}"

Syntax

An expansion expression MUST:

• be in string format ("...")

• start with ${

• end with }

• contain only a (dot-separated) path to a property located in an available scope (depends on context).

{
    "property": "${scope.path.to.property}",
}

Expansion expression MAY:

• be embedded in a string

• be combined

{
    "embedded": "Embedded: ${path.to.property}",
    "combined": "test-${path.to.first}-${path.to.second}"
}

Objects

Objects can contain values, lists and objects named by keys.

Segments in paths/keys separated by . traverse nested properties in objects:

  ${user.address.city}

Use \. to include a literal dot in a key name, rather than traversing a nested property:

  ${scope.key\.name}    →  looks up key "key.name"
  ${scope.key.name}     →  looks up "name" inside "key"

For keys that contain dots, spaces, or other special characters bracket notation can be used:

${path.to.obj['key.with.dots']}
${path.to.obj['key with spaces']}

Lists

Lists can contain values, objects and lists.

Elements in lists are accessed using bracket or index-property notation:

// Expression resolving to third element of list 'list'
"${path.to.list[2]}" // Bracket notation
"${path.to.list.2}"  // Index property

List elements are accessed by zero-based index:

  ${list.0}     →  first element
  ${list[0]}    →  first element (bracket notation)
  ${list.2}     →  third element (index property notation)

Special keywords that can be used with lists:

// size
${list.size}
${list.length}
${list.len}

// first element
${list.first}

// last element
${list.last}

// all elements
${list.all}
${list.values}

Misc

Dot and bracket notation can be freely combined:

  ${path.to.arr[1]['display.name']}

Scopes and types

Scopes are the named top level objects containing expansion data (for example request or session). Available scopes depends on the context.

Data in scopes are accessed different depending on the type of objects included in the path. An expansion path can contain the following types of objects:

• primitive types ("values", ie string, number, etc)

• objects

• arrays

A primitive type is always a leaf (last element of an expansion path) and can only contain a value, not other primitives, object or arrays.

// Expand primitive 'value' in scope 'scope'
${scope.value}

Objects can contain other objects, primitives and arrays. When objects are nested, we traverse them using a dot-separated path containing the

// Expand property 'prop' on object 'obj' in scope 'scope'
${scope.obj.prop}

${scope.obj01.prop01.obj02.prop02}

Arrays are list of primitives, objects or arrays. Elements in an array are referenced using bracket or index property notation, where the first element has index 0.

${scope.arr.0} // first element of array 'arr' in scope 'scope'
${scope.arr[1]} // second element -"-