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": "${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}"
}

If an expansion expression path contains an array, elements are referenced using an index property (zero based, first element has index 0):

"${path.to.array.2}" // Third element of array 'array'

It is not recommended to use arrays in expansions since expressions becomes tied to the order of the array elements. Use objects instead with named properties (instead of index).

Scopes

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 (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 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 -"-

If an array contains complex types (objects or other arrays) and when properties in these elements are to be referenced, the following value-syntax must be used:

${scope.arr.1.value.prop} // property 'prop' on second element in arr

The value property of an array element is the actual value of the element whilst the index property of the array is the string representation of the element.

The value property is only used when traversing content of an array, not when targeting an element for expansion.