> Part of the walkerOS documentation. Project overview and full index: # 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. ## The one rule[​](#the-one-rule "Direct link to The one rule") walkerOS uses **two separator characters**, each with a clear meaning: | Separator | Meaning | | --------- | ----------------------------------------------------------------------------------------------- | | **`.`** | 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 that rule. There are no exceptions. ## All references[​](#all-references "Direct link to 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 process.env[NAME] $env.NAME:default read process.env[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 value (resolved at deploy time) $code:(event) => ... inline JavaScript (resolved at bundle time) ``` ## `$var.` — variables[​](#var--variables "Direct link to 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": { "destinations": { "gtag": { "config": { "settings": { "ga4": { "measurementId": "$var.measurementId" } }, "mapping": { "order": { "complete": { "data": { "map": { "items": "$var.ga4Items" } } } } } } }, "api": { "config": { "settings": { "endpoint": "$var.api.url", "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. Object or array values throw, scalars only. * Variables may reference other variables. Resolution is recursive with cycle detection. **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[​](#env--environment-variables "Direct link to env--environment-variables") Read from `process.env` at runtime. Optionally provide a literal fallback with the `:default` suffix. ``` { "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`. ## `$contract.` — contract references[​](#contract--contract-references "Direct link to 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](https://www.walkeros.io/docs/getting-started/flow/contract.md) for the full structure. ``` { "contract": { "default": { "schema": { "properties": { "globals": { "required": ["country"] } } }, "events": { "product": { "add": { "properties": { "data": { "required": ["id", "name"] } } } } } } }, "flows": { "web": { "destinations": { "ga4": { "validate": { "events": "$contract.default.events", "schema": "$contract.default.schema" } } } } } } ``` ## `$store.` — store wiring[​](#store--store-wiring "Direct link to 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": { "stores": { "cache": { "package": "@walkeros/server-store-fs" } }, "sources": { "http": { "package": "@walkeros/server-source-http", "env": { "store": "$store.cache" } } } } } } ``` Store IDs are plain identifiers (camelCase). The `.` is the separator, not a path walker, store IDs do not contain dots. ## `$secret.` — secrets[​](#secret--secrets "Direct link to secret--secrets") Inject a secret resolved at deploy time. Secrets are stored outside the config and never written into customer databases alongside the flow. ``` { "flows": { "web": { "destinations": { "api": { "config": { "settings": { "headers": { "Authorization": "Bearer $secret.API_TOKEN" } } } } } } } } ``` Secret names are uppercase: `[A-Z0-9_]+`. The `.` is the separator, secrets have no internal structure. 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. Secrets resolve on server flows only. ## `$code:` — inline code[​](#code--inline-code "Direct link to 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:(entity) => entity.entity === 'product'" } } } ``` The `:` here marks the **payload**. Nothing after the colon is looked up, it is compiled as-is. ## Cascade and resolution order[​](#cascade-and-resolution-order "Direct link to Cascade and resolution order") `variables` can live at three levels. Priority (highest wins): 1. Step level (`sources.*`, `transformers.*`, `destinations.*`, `stores.*`) 2. Flow level (`flows..variables`) 3. Config root (`variables`) Resolution runs at `getFlowSettings()` in `@walkeros/core`, the runtime replaces every reference before the bundler or collector sees the config. ## What else to read[​](#what-else-to-read "Direct link to What else to read") * [`@walkeros/core` reference exports](https://github.com/elbwalker/walkerOS/blob/main/packages/core/src/references.ts): `REF_VAR_FULL`, `REF_VAR_INLINE`, `REF_ENV`, `REF_CONTRACT`, `REF_FLOW`, `REF_STORE`, `REF_SECRET`, `REF_CODE_PREFIX`. The single source of truth for the regex patterns. Also exports `scanFlowRefs(value)` which walks any value (string, array, object) and returns every `$flow.` reference found, including refs nested inside `$code:` snippets. * [Stores guide](https://www.walkeros.io/docs/stores.md): wiring stores via `$store.`. * [Mapping guide](https://www.walkeros.io/docs/mapping.md): `$code:` and mapping-value shortcuts.