Skip to main content
Ask your AI

Reference Syntax

walkerOS flow configs (flow.json) support dynamic references inside string values. They let you pull in variables, environment values, contract fragments, store instances, secrets, and inline JavaScript without duplicating configuration.

Snippets on this page show only the keys a reference needs; a complete flow.json also has "version": 4 and its steps.

The one rule​

walkerOS uses two separator characters:

SeparatorMeaning
.A key or path. The resolver looks up what follows in a map or walks it as a dotted path.
:A literal value or raw-code payload. The resolver uses what follows verbatim; it is not a name.

Every reference follows this rule, without exceptions.

All references​

$var.name look up variables[name] (whole-string returns native type)
$var.name.deep.path walk a dotted path inside the variable
$env.NAME read environment variable NAME (web: bundle time, server: run time)
$env.NAME:default read NAME with a literal fallback
$contract.name inject a whole named contract entry
$contract.name.events walk the contract path
$store.id inject a store instance (resolved at bundle time)
$secret.NAME inject a secret (server only, read from the environment at start)
$code:(event) => ... inline JavaScript (resolved at bundle time)

$var.: variables​

Look up a value in the variables map at config, flow, or step level. Step overrides flow overrides config.

Variables hold any JSON value, scalars (string, number, boolean), objects, arrays, or whole mapping templates. The reference may include a deep path that walks the value.

{
"variables": {
"measurementId": "G-XXXXXX",
"ga4Items": {
"loop": ["nested", { "map": { "item_id": "data.id" } }]
},
"api": { "version": "v2", "url": "https://api.example.com" }
},
"flows": {
"web": {
"config": { "platform": "web" },
"destinations": {
"gtag": {
"package": "@walkeros/web-destination-gtag",
"config": {
"settings": {
"ga4": { "measurementId": "$var.measurementId" }
},
"mapping": {
"order": {
"complete": {
"data": { "map": { "items": "$var.ga4Items" } }
}
}
}
}
},
"api": {
"package": "@walkeros/web-destination-api",
"config": {
"settings": {
"url": "$var.api.url",
"headers": { "X-Api-Version": "$var.api.version" }
}
}
}
}
}
}
}

Resolution rules:

  • A whole-string reference ("$var.api.url") replaces the value with the variable's native type. Object, array, number, and boolean values are preserved.
  • An inline reference ("Bearer $var.token") substitutes a scalar mid-string; an object or array value throws.
  • Variables may reference other variables. Resolution is recursive with cycle detection.

In flow-complete.json, the tested example flow, variables live at all three levels:

/variables
{
  "currency": "EUR",
  "gcp": {
    "project": "$env.GCP_PROJECT:demo-project",
    "dataset": "$env.BQ_DATASET:walkeros",
    "topic": "$env.PUBSUB_TOPIC:walkeros-events"
  }
}
Root variables are shared by all flows; a flow or a step can override them. Guide chapter references
/flows/server/variables
{
  "logLevel": "$env.LOG_LEVEL:INFO"
}
Flow variables win over root variables for one flow. Guide chapter references
/flows/server/destinations/piwikpro/variables
{
  "siteId": "$env.PIWIK_SITE_ID:e8f3a1c2-0b4d-4e5f-9a6b-7c8d9e0f1a2b"
}
Step variables win over flow and root variables for one step. Guide chapter references

A whole-string reference, a deep path and an inline reference:

/flows/web/destinations/ga4/config/policy/data.currency/1/value: "$var.currency". A whole-string $var keeps the variable type. Guide chapter references

/flows/server/destinations/pubsub/config/settings/projectId: "$var.gcp.project". $var.gcp.project reads a path inside a variable. Guide chapter references

/flows/warehouse/sources/pubsub/config/setup/deadLetterPolicy/deadLetterTopic: "projects/$var.gcp.project/topics/walkeros-dead-letter". Inside a longer string $var is replaced in place, here in a full topic name. Guide chapter references

Naming convention: when variables hold structures (mapping templates, matchers, consent objects), pick a name that signals the shape, for example ga4ItemMapping, ga4ItemsLoop, consentMarketing, getMastertagJs. Keep the convention consistent within a single config; we don't enforce a global prefix or suffix rule.

$env.: environment variables​

A web flow reads the value at bundle time, from its build environment (see below), and the bundle fails if the variable is not set. A server flow's bundle reads process.env when it runs; an unset variable resolves to undefined, and inside a longer string it becomes the text undefined. On both platforms the :default suffix gives a literal fallback for an unset variable.

{
"variables": {
"apiUrl": "$env.API_URL:http://localhost:8080/collect",
"pixelId": "$env.META_PIXEL_ID"
}
}

The : here is the default-value separator, not a name delimiter. The token after : is used verbatim.

Use $env. for non-secret config (IDs, hostnames, regions). For credentials, tokens, and private keys managed by the secret manager, use $secret.: the deploy pipeline only injects values referenced as $secret.NAME.

/variables/gcp/project: "$env.GCP_PROJECT:demo-project". $env.NAME:default works out of the box and takes the environment value when set. Guide chapter references

/flows/web/collector/custom/environment: "$env.ENVIRONMENT". $env without a default must be set: this web flow declares ENVIRONMENT in config.bundle.env, so the build never misses it. Guide chapter references

A local walkeros bundle resolves a web flow's $env from your shell environment with the set the flow declares under config.bundle.env on top; a hosted build reads the declared set alone (see build-time values):

/flows/web/config/bundle/env
{
  "ENVIRONMENT": "production"
}
Web $env is resolved at build time: a local walkeros bundle reads the shell environment with this declared set on top. Guide chapter references

$contract.: contract references​

Inject a fragment of a named contract entry. Same whole-string and deep-path rules as $var.. The contract is fully resolved (extend + wildcards) before path access, so the value you get is the merged shape.

See Contract for the full structure.

/flows/server/transformers/validate/config/settings/contract/0: "$contract.server". $contract.server hands the resolved contract to the validate step. Guide chapter references

{
"contract": {
"default": {
"schema": {
"properties": {
"globals": { "required": ["country"] }
}
},
"events": {
"product": {
"add": { "properties": { "data": { "required": ["id", "name"] } } }
}
}
}
},
"flows": {
"web": {
"config": { "platform": "web" },
"transformers": {
"validate": {
"package": "@walkeros/transformer-validate",
"config": {
"settings": {
"contract": ["$contract.default"],
"mode": "strict"
}
}
}
}
}
}
}

A deep path such as $contract.default.schema injects only that part of the resolved entry, here the full-event JSON Schema, which the validate transformer also accepts as a contract entry.

$store.: store wiring​

Inject a store instance declared under stores. Wired through a component's env so the bundler can resolve to the real store at build time.

{
"flows": {
"server": {
"config": { "platform": "server" },
"stores": {
"assets": {
"package": "@walkeros/server-store-fs",
"config": { "settings": { "basePath": "./public" }, "file": true }
}
},
"transformers": {
"file": {
"package": "@walkeros/server-transformer-file",
"config": { "settings": { "prefix": "/static" } },
"env": { "store": "$store.assets" }
}
}
}
}
}

Store IDs are plain identifiers (camelCase). The . is the separator, not a path walker: store IDs contain no dots.

/flows/server/transformers/file/env/store: "$store.assets". $store.assets injects a store into a step. Guide chapter references

$secret.: secrets​

Inject a secret into a server flow. The value is in neither the config nor the bundle: the bundle reads the environment variable of the same name when it starts, and stops with required secret "NAME" is not set when it is missing or empty.

{
"flows": {
"server": {
"config": { "platform": "server" },
"destinations": {
"api": {
"package": "@walkeros/server-destination-api",
"config": {
"settings": {
"url": "https://api.example.com/events",
"headers": { "Authorization": "$secret.API_AUTHORIZATION" }
}
}
}
}
}
}
}

Secret names are uppercase: [A-Z0-9_]+. The . is the separator; secrets have no internal structure.

A $secret. reference must be the entire string value. Inside a longer string it would not resolve, so walkeros validate and the bundle reject it (MALFORMED_REFERENCE). When a header needs a prefix, store the complete value in the secret, for example Bearer abc123 for API_AUTHORIZATION above.

/flows/server/destinations/pubsub/config/credentials: "$secret.GCP_SA". $secret is read at start and never baked into an artifact; web flows reject it. Guide chapter references

Use $secret. for credentials, tokens, and private keys (for example a service account JSON on config.credentials). The app's deploy pipeline detects $secret.NAME references and injects the managed secret value into the server runner's environment at runtime. A managed secret referenced as $env.NAME is not injected, so reach for $secret. whenever the value comes from the secret manager. In a web flow, a $secret. reference is a validate and bundle error.

$code:: inline code​

Embed a JavaScript function as a string. The bundler compiles the payload into real JS at build time. Everything after $code: is the raw function body.

{
"variables": {
"onlyProducts": {
"condition": "$code:(event) => event.entity === 'product'"
}
}
}

The : here marks the payload. Nothing after the colon is looked up; it is compiled as is.

/flows/web/destinations/collect/config/settings/transform: "$code:(event) => { const { timing, ...rest } = event; return rest; }". $code: puts a function into JSON. Guide chapter references

$flow.: cross-flow references​

Read a value from another flow's config block in the same file. The web flow sends to the server flow's URL:

/flows/web/destinations/collect/config/settings/url: "$flow.server.url". $flow.server.url points the browser at the server flow; it is whole-string only. Guide chapter references

A flow name in a reference starts with a letter or _, followed by letters, digits, _ or -, so $flow.tracking-server.url reads the url of the flow tracking-server. The first . after the name starts the path.

See Cross-flow references for the rules.

Request values: ingest​

Request context is not a $ reference. A server source lifts it into ingest with its config.ingest mapping, and later steps read it by path (ingest.ip, ingest.path), for example in a route match or a state key:

/flows/server/sources/express/config/ingest
{
  "map": {
    "ip": "headers.x-client-ip",
    "path": "path",
    "method": "method",
    "url": "url",
    "body": "body",
    "origin": "headers.origin",
    "userAgent": "headers.user-agent",
    "acceptLanguage": "headers.accept-language"
  }
}
ingest keeps the request context (ip, path, headers) for later steps without putting it on the event. Guide chapter server-entry

Cascade and resolution order​

variables can live at three levels. Priority (highest wins):

  1. Step level (sources.*, transformers.*, destinations.*, stores.*)
  2. Flow level (flows.<name>.variables)
  3. Config root (variables)

walkeros bundle resolves $var, $contract, $flow and a web flow's $env with getFlowSettings() from @walkeros/core, wires $store and compiles $code:. A server flow's $env and $secret stay reads of the environment when the bundle starts.

Whole-value and inline references​

$flow., $store., $secret. and $contract. resolve only when the reference is the entire string value. $var. and $env. also resolve inside a longer string. walkeros validate and the bundle fail with MALFORMED_REFERENCE on a whole-value reference that would not resolve:

  • Malformed: "$flow.server.url/collect" or "$secret.api_key" does not match the reference grammar ($secret. names are uppercase letters, digits and _), so it would not resolve.
  • Inline: "https://x/$store.cache" uses $store. mid-string, so it would ship as literal text. Use the reference as the entire value, or compose the string with $var or $env.

This check skips $code: values, $comment values, the root contract block, a step's config.settings.contract, and the title and description of the config, a flow, a step or a step example.

What else to read​

  • @walkeros/core reference exports: REF_VAR_FULL, REF_VAR_INLINE, REF_ENV, REF_CONTRACT, REF_FLOW, REF_FLOW_INLINE, REF_FLOW_NAME, REF_STORE, REF_SECRET, REF_CODE_PREFIX, the single source of truth for the regex patterns. It also exports scanFlowRefs(value) which walks any value (string, array, object) and returns every $flow.<name> reference found, including refs nested inside $code: snippets.
  • Stores guide: wiring stores via $store..
  • Mapping guide: $code: and mapping-value shortcuts.
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)