Property 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 (dot-separated) path to another element in the same (logical) configuration.

Expansion expressions are written in the following format:

"${path.to.property}"

Note

Expansion is performed after file inclusion allowing included files to also contain expansions.

Syntax

An expansion expression MUST:

• be in string format ("...")
• start with ${
• end with }
• contain only a (dot-separated) path to another property in the current configuration

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

Expansion expression MAY:

• be embedded in a string
• be combined

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

If an expansion expression path contains an array, elements are referenced using an index property:

"${path.to.array.2.element}"

Caution

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

Bracket notation

Properties with complex names — such as URLs, OIDs, or names containing dots, colons, or other special characters — cannot be referenced using dot notation. Use bracket notation instead:

"${scope['urn:oid:1.3.6.1.4.1.5923.1.1.1.6']}"
"${scope[\"key.with.dots\"]}"

Dot notation and bracket notation can be combined:

"${scope.inner['key:with:colons']}"

Note

Bracket notation is only supported in ${...} expressions. Mustache {{...}} syntax does not support complex property names.

Scopes

Scopes are the named objects containing expansion result values.

The following scopes are available in addition to the configuration itself:

Name	Description
system	Java system properties
env	Process environment variables
secrets	External secrets. Requires secrets management to be enabled, see Secrets management.

Caution

Do NOT use dotted names for properties in system and env scope.

Examples

To externalize a secret from the configuration file, define a system property containing the value and use expansion:

// Define system property
-DldapBindPassword=secret

// Expansion
"bind_password": "${system.ldapBindPassword}"

Use a path defined in the environment in the configuration:

// Set base_dir to value of $HOME
"base_dir": "${env.HOME}"