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, 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

$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

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. Object or array values throw, scalars only.
• 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

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.

/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/server/transformers/fingerprint/config/settings/salt: "$env.FINGERPRINT_SALT". $env without a default must be set: a secret salt never gets a public default. Guide chapter references

Web flows resolve $env at build time, from the set the flow declares under config.bundle.env:

/flows/web/config/bundle/env

{
  "ENVIRONMENT": "production"
}

Web $env is resolved at build time from this declared set, so every build is the same. 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 do not contain 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 resolved at deploy time. Secrets are stored outside the config and never written into customer databases alongside the flow.

{
  "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 is not resolved and stays literal text. 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. Secrets resolve on server flows only.

$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.

/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

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": "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)

Resolution runs at getFlowSettings() in @walkeros/core, the runtime replaces every reference before the bundler or collector sees the config.

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 warns about 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.

$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 are not checked.

What else to read

• @walkeros/core reference exports: 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.<name> reference found, including refs nested inside $code: snippets.
• Stores guide: wiring stores via $store..
• Mapping guide: $code: and mapping-value shortcuts.