6.4 Placeholder Resolutions - Connectable Elements
Placeholder Resolution (${...})
Overview
Placeholders in the form ${...} allow values to be resolved dynamically at runtime.
They are used to connect datapoints, pass input through connectors, and interpolate values into strings.
Placeholders can be used anywhere a string value is accepted.
Syntax
${expression}
The expression is evaluated against the current execution context.
Expression Language
Internally, placeholder expressions are evaluated using a JSONata-compatible expression engine (see also: Using JSONata).
Note: Only the documented namespaces and fields are considered stable and supported.
Placeholder expressions use a JSONata-compatible expression language. When accessing object properties, the allowed characters depend on the notation used.
An unquoted property name has to be a valid JSONata identifier:
- Letters:
A–Z,a–z - Digits:
0–9(not as the first character)
A name containing anything else — a dash, a space, a period — is still reachable, but only if it is quoted in the expression. Backticks, single quotes and double quotes all work:
${response.firstRef.headers.'content-type'}
${response.firstRef.headers.`content-type`}
Unquoted, those characters are read as JSONata operators: ref.my-value is parsed as ref.my minus
value, which evaluates to nothing. No error is raised — the placeholder simply resolves to empty.
That is why names you create yourself — above all a connector element's ref — should be camelCase:
see Naming Convention Guidelines.
Quoting is for names you do not control, such as HTTP header names in a response.
Resolution Rules
- Placeholders are resolved before execution of the element
- Multiple placeholders in a string are supported
- Resolution is context-dependent: which namespaces exist depends on where the placeholder sits
Namespaces by scope
This is the complete set. A namespace that is not listed for a scope does not exist there, and an expression referencing it resolves to nothing rather than failing.
| Namespace | Datapoint | Connector element | Input transformer | Output transformer | Description |
|---|---|---|---|---|---|
input | yes | yes | yes | yes | The current execution payload. In a connector this is the output of the previous element |
env | yes | yes | yes | yes | Values of environment elements registered in the repository |
root | — | yes | — | — | The payload the connector was invoked with, unchanged for the whole execution |
ref | — | yes | — | — | Documented output of an earlier element in the same connector |
response | — | yes | — | — | Full HTTP response of an earlier element in the same connector |
params | — | yes | — | — | The parameters declared on the current connector element |
output | — | — | — | yes | The result of the element the transformer is attached to |
template | — | — | — | — | Resolved once at template instantiation, not at execution time |
A datapoint invoked on its own therefore has only input and env. The same datapoint used inside a
connector can additionally be given root, ref, response and params values — but only through the
parameters of the connector element that calls it, because those namespaces are resolved in the
connector's context, not the datapoint's.
ref, response, root or params inside a datapoint definitionThey are not part of a datapoint's resolution context. Pass the value in from the connector element's
parameters instead, and read it in the datapoint as ${input.<name>}.
Nothing warns you about this. There are no datapoint-specific validation rules, so such an expression is stored without complaint and resolves to nothing at execution time — the datapoint runs and receives an empty parameter. See Semantic Validation Rules for what the editor does and does not check.
Environment variables (env)
${env.<key>} resolves against the environment elements registered in the repository, so a value that
differs per deployment — an API base URL, a tenant identifier — can live outside the datapoint definition
and move with the environment rather than with the solution.
The lookup happens lazily: it is performed only when an expression in the element actually contains
env., and the resolved values are not written into the stored definition.
Placeholders in Datapoints
Datapoints support placeholders to dynamically resolve values from their execution input.
Placeholders are resolved before the datapoint is executed.
Supported namespaces
| Namespace | Description |
|---|---|
input | Input object passed to the datapoint at execution time |
env | Values of environment elements registered in the repository |
These two are the only namespaces available in a datapoint definition. See Namespaces by scope.
Example datapoint (minimal)
{
"id": "example-dp-echo-postman",
"type": "datapoint",
"datapoint": {
"type": "http",
"parameters": {
"echo": "${input.text}"
}
}
}
Execution body
{
"id": "echo-postman",
"input": {
"text": "test"
}
}
Placeholder resolution
${input.text} → "test"
Example datapoint response
{
"state": "SUCCESS",
"result": {
"data": {
"echo": "test"
}
}
}
Output contract
When a datapoint is used inside a connector, its result payload is exposed via:
ref.<refName>
For this datapoint, the documented and stable output is:
ref.<refName>.data.echo : string
Schemas (optional)
Datapoints may define optional input and output schemas.
- Schemas are informational only
- Schemas are not enforced at runtime
- Schemas document stable fields intended for use by connectors
Full datapoint definition
The following section shows the complete datapoint definition, including schemas, for reference.
{
"id": "example-dp1-echo-postman",
"type": "datapoint",
"version": "0.0.1",
"displayName": "echo postman endpoint",
"tags": [
"automated-testing",
"bootstrap-testing"
],
"description": "",
"deprecated": false,
"name": "echo postman endpoint",
"datapoint": {
"type": "http",
"http": {
"url": "https://postman-echo.com/post",
"method": "POST",
"headers": {
"content-type": "application/json"
}
},
"parameters": {
"echo": "${input.text}"
}
},
"owner": "",
"input": {
"schema": {
"type": "json",
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "echo-postman input",
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"description": "Text that will be echoed by the datapoint."
}
}
}
}
},
"output": {
"schema": {
"type": "json",
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "echo-postman output",
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"required": [
"echo"
],
"properties": {
"echo": {
"type": "string",
"description": "Echoed value originating from input.text."
}
}
}
}
}
}
}
}
Connectors
Connectors orchestrate the execution of multiple connectable elements and allow data to be passed between them using placeholders.
Elements are executed sequentially in the order they are defined.
Placeholder namespaces
The following namespaces are available when resolving placeholders inside connectors.
| Namespace | Description |
|---|---|
input | The current execution payload — the output of the previous element |
root | The payload the connector was invoked with, unchanged throughout |
ref | Documented output of previously executed elements |
response | Full HTTP response of previously executed elements |
params | The parameters declared on the current connector element |
env | Values of environment elements registered in the repository |
input
The input namespace represents the current execution payload.
In connectors, this payload may originate from the initial connector input or from a previous execution step, depending on the execution order.
root
The root namespace provides access to the initial execution context of the connector.
This allows access to values that remain constant throughout the connector execution.
ref
The ref namespace exposes the documented output payload of previously executed connector elements.
For an element with the reference firstRef, the documented output is accessible under:
ref.firstRef
Only fields documented by the referenced datapoint should be accessed via ref.
response
The response namespace exposes the full HTTP response of executed connector elements.
This allows access to HTTP-level information such as status codes, headers, and raw response bodies.
For an element with the reference firstRef, the HTTP response is available under:
response.firstRef
Accessing HTTP response properties
HTTP response properties can be accessed using JSONata-compatible expressions.
When property names contain special characters (such as hyphens), quoted notation must be used.
Example:
${response.firstRef.headers.'content-type'}
Relationship between ref and response
| Namespace | Purpose |
|---|---|
| ref | Stable, documented output intended for data flow |
| response | Full HTTP response including protocol-level details |
Use ref.* for business logic and data passing between elements.
Use response.* only when HTTP-specific information is required.
⚠️ Note: The "response" placeholder only works for http responses and only works on server side - connectivity triggered from an OLIVE micro frontend can not interpret the response placeholder correctly.
Execution order
- Connector elements are executed top to bottom
- Only elements that have already been executed can be referenced via
reforresponse - Placeholders are resolved before each element execution
Special cases (advanced usage)
Placeholders in datapoint HTTP properties
Placeholders can be used inside certain datapoint HTTP configuration properties,
such as URLs and header values.
This allows datapoints to be more flexible and environment-agnostic.
Example
{
"datapoint": {
"type": "http",
"http": {
"url": "https://${input.postmanUrl}/post",
"method": "POST",
"headers": {
"content-type": "${input.contentType}"
}
},
"parameters": {
"echo": "${input.text}"
}
}
}
Important limitations
The following is not supported:
- Using placeholders to generate property keys
- Using placeholders to dynamically change parameter names
Placeholders in datapoint properties are supported for values only.
Recommendation
- Prefer placeholders in parameters
- Use placeholders in HTTP properties sparingly
- Treat this as advanced usage
Related
- Security in Connectivity Engineering — the character rules placeholders must satisfy from OLIVE 1.3