Interpolations and References

Interpolations and references are additional syntactical constructs that ESC layers on top of YAML to allow users to reuse properties to construct new values.

References take the form ${property-path}. References may appear alone or embedded within strings. The former case is referred to as a bare reference; the latter is an interpolation.

Property paths

Property paths–used throughout the Pulumi ecosystem–are JavaScript-inspired expressions that refer to properties within JSON-like values.

The syntax supports both dot notation and bracket notation. For keys that contain special characters (i.e. [, ], ", or .) or begin with a digit, bracket notation is required.

Binding references

In the context of ESC, references either refer to properties in the evaluated environment in which they are contained or to built-in properties.

Interpolations and references are early-bound: each reference is evaluated within the context of the environment in which it is contained. This allows the author of an environment definition to reliably predict the form of the value referred to by a reference.

Early binding contrasts with late binding, which would evaluate references within the context of the top-level environment and its entire import stack. ESC does not currently support late-bound references.

Bare references

Bare references evaluate to a copy of the referenced value.

Example

values:
  user:
    name: Real Name
    login: user-login
  user-copy: ${user}

Evaluated result

{
  "user": {
    "name": "Real Name",
    "login": "user-login"
  },
  "user-copy": {
    "name": "Real Name",
    "login": "user-login"
  }
}

Interpolations

Interpolations evaluate to the string representation of the referenced value.

Example

values:
  user:
    name: Real Name
    login: user-login
  greeting: Hello, ${user.name}!

Evaluated result

{
  "user": {
    "name": "Real Name",
    "login": "user-login"
  },
  "greeting": "Hello, Real Name!"
}

Built-in properties

Besides the properties defined within an environment, references can access three built-in properties: information about the user evaluating an environment (context), other environments in the organization (environments), and imported environments (imports). See Built-in properties.