# Property expansion

Documentation owner: product `access`; documentation version: `3.9.1`.
Source: `content/products/access/3.9.1/configuration-reference/property-expansion.md` at commit `eaf7a020437971baeee95e87eaf963636040ac71`.

## 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](/products/access/configuration-reference/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}"
```