Destaris
Browse the docs

Expressions (JSONata)

How to reference and reshape data with JSONata expressions.

Wherever a step needs to read or reshape data — a transform, a branch condition, the items for a loop, an HTTP body — you write a JSONata expression. JSONata is a small, readable query-and-transform language for JSON.

Where expressions are used

| Field | Node | What it does | | --- | --- | --- | | expression | task.transform | Reshape data into this node's output. | | expression | task.branch | Produce the value the outgoing edges match with when. | | items | task.foreach | Resolve to the list to iterate. | | while | task.loop | A condition; the loop repeats while it's true. | | bodyExpression | task.http | Build the request body. | | items / key | task.cache-unseen, task.cache-mark | The list and its dedupe key. |

What you can reference

An expression runs against a scope built from the run so far:

  • Any earlier step, by its node id — fetchIssues.items, triage.priority. A node's output is exactly what that step returned.
  • trigger — the trigger's payload, e.g. trigger.repo.
  • Inside a task.foreach or task.loop body: item (the current element), index (0-based), and prev (the previous iteration's result, or null on the first).

Common patterns

/* Pick a field from an earlier step */
triage.summary

/* Filter a list — keep comments not written by the agent */
fetchComments.comments[author != 'agent']

/* A branch/loop condition (booleans and comparisons) */
$count(unhandled) > 0
triage.priority = 'urgent'

/* Build an object, e.g. an HTTP body. `&` concatenates strings */
{ 'text': '🔴 ' & triage.summary }

/* Map a list into a new shape */
fetchIssues.items.{ 'id': number, 'title': title }

JSONata ships a large function library — $count, $sum, $map, $filter, $string, $substringAfter, and many more. See the JSONata documentation for the full reference.

Branches return a value, not just true/false

A task.branch expression evaluates to a value, and each outgoing edge declares which value it handles with when:

- id: route
  type: task.branch
  config: { expression: "triage.priority" }

edges:
  - { from: route, to: notify, when: "urgent" }
  - { from: route, to: log, when: "normal" }

Not to be confused with

Two other syntaxes appear in configs and are not JSONata:

  • ${NAME} — inserts a setting (a secret or variable) by name into a string, for example Bearer ${API_TOKEN} in an HTTP header. Values are never shown, only referenced. See Bring your own auth.
  • {{ ... }} — simple templating in a task.command, e.g. echo {{trigger.who}}.