JSONPath

The mapping engine is jsonpath-plus running in an embedded JavaScript runtime. This page lists what that build actually supports. Every result below was produced by running the expression through the engine the flow uses. Unless a section says otherwise, the examples run against this data:

{
  "trigger": { "amount": 1500 },
  "fetch_customer": { "name": "Alice Smith", "email": "alice@example.com", "tier": "premium" },
  "fetch_order": {
    "address": { "city": "Leeds", "contact": { "email": "ops@example.com" } },
    "items": [
      { "product": "Widget",    "price": 149.99, "qty": 1, "active": true,  "tags": ["a", "b"] },
      { "product": "Gadget",    "price": 150.00, "qty": 3, "active": false, "tags": ["c"] },
      { "product": "Doohickey", "price": 9.99,   "qty": 2, "active": true,  "tags": [] }
    ]
  }
}

An expression must start with $. — those two characters are what marks a string as a path. $['fetch_customer']['name'], $[0] and a bare $ all start with $ but not $., so they are copied through as literal text and never resolved. Write $.fetch_customer['name'] instead: bracket notation is fine anywhere after the opening $..

Selectors

Expression	Result
`$.fetch_customer.name`	`"Alice Smith"`
`$.fetch_order.address.city`	`"Leeds"`
`$.fetch_order.items[0].product`	`"Widget"`
`$.fetch_order.items[0,2].product`	`["Widget", "Doohickey"]`
`$.fetch_order.items[*].product`	`["Widget", "Gadget", "Doohickey"]`
`$.fetch_order.items.*.product`	`["Widget", "Gadget", "Doohickey"]`
`$.fetch_order.items[].tags[]`	`["a", "b", "c"]`
`$.fetch_order.items.length`	`3`
`$.`	the whole data object

Bracket notation

Needed whenever a key is not a plain identifier — spaces, dots, hyphens, or a numeric key.

Expression	Result
`$.data['first name']`	`"x"`
`$.data['a.b']`	`"x"`
`$.data['property-name']`	`"x"`
`$.data['123']`	`"x"`

Slices

Expression	Result
`$.fetch_order.items[0:2].product`	`["Widget", "Gadget"]`
`$.fetch_order.items[1:].product`	`["Gadget", "Doohickey"]`
`$.fetch_order.items[::2].product`	`["Widget", "Doohickey"]`
`$.fetch_order.items[-2:].product`	`["Gadget", "Doohickey"]`
`$.fetch_order.items[-1:].product`	`"Doohickey"`

A bare negative index does not work. $.fetch_order.items[-1] returns [], not the last item. Only the slice form counts from the end, so the last element is [-1:] — and because a one-element slice is a single hit, it returns the value itself rather than a one-item array.The index-free alternative is a script index: $.fetch_order.items[(@.length-1)].product returns "Doohickey".

Recursive descent

.. searches every level below the point it appears.

Expression	Result
`$..email`	`["alice@example.com", "ops@example.com"]`
`$..price`	`[149.99, 150, 9.99]`
`$.fetch_order..email`	`"ops@example.com"`
`$..items[?(@.price>100)].product`	`["Widget", "Gadget"]`

Parent and property operators

Expression	Returns
`$.fetch_order.items[?(@.qty>2)]^`	the parent of each match — here the whole `items` array
`$.fetch_customer~`	`"fetch_customer"` — the matched key’s name rather than its value

Filters

A filter is [?( … )]. The body is a JavaScript expression evaluated once per candidate, with @ bound to the candidate.

Expression	Result
`$.fetch_order.items[?(@.price>100)].product`	`["Widget", "Gadget"]`
`$.fetch_order.items[?(@.qty>2)].product`	`"Gadget"`
`$.fetch_order.items[?(@.price>9999)].product`	`[]`
`$.fetch_order.items[?(@.active===true)].product`	`["Widget", "Doohickey"]`
`$.fetch_order.items[?(@.active==true)].product`	`["Widget", "Doohickey"]`
`$.fetch_order.items[?(@.qty!=1)].product`	`["Gadget", "Doohickey"]`
`$.fetch_order.items[?(!@.active)].product`	`"Gadget"`
`$.fetch_order.items[?(@.active===true && @.price>100)].product`	`"Widget"`
`$.fetch_order.items[?(@.price>=50 && @.price<=150)].product`	`["Widget", "Gadget"]`
`$.fetch_order.items[?(@.qty*@.price>400)].product`	`"Gadget"`
`$.fetch_order.items[?(@.tags.length>0)].product`	`["Widget", "Gadget"]`
`$.fetch_order.items[?(@.tags[0]==='a')].product`	`"Widget"`

Ordinary JavaScript methods on the candidate’s own values work:

Expression	Result
`[?(@.product.startsWith('G'))]`	`"Gadget"`
`[?(@.product.includes('adg'))]`	`"Gadget"`
`[?(@.product.toLowerCase()==='widget')]`	`"Widget"`
`[?(@.product.match(/^W/))]`	`"Widget"`
`[?(@.tags.indexOf('a')>-1)]`	`"Widget"`
`[?(typeof @ === 'string')]`	the string members of an array

A filter may contain another filter, as long as the inner one is the whole test:

$.users[?(@.orders[?(@.total>1000)])]     selects users with an order over 1000

It cannot be followed by anything. $.users[?(@.orders[?(@.total>1000)].length>5)] fails to parse with Unexpected "?" at character 12, and combining it with && returns no matches rather than an error. Count in an Eval step instead.

Context variables

Variable	Meaning	Verified example
`@`	the candidate itself	`[?(typeof @ === 'string')]`
`@root`	the whole data object	`$.products[?(@.categoryId===@root.trigger.selected_category)]`
`@parent`	the candidate’s parent object	`$.categories..products[?(@parent.tier==='premium')]`
`@property`	the candidate’s key or array index	`$.items[?(@property!==0)]` → drops the first element
`@parentProperty`	the parent’s key	`$.data..[?(@parentProperty!=='hidden')]`
`@path`	the JSONPath string to the candidate	`$.store.book[?(@path!=="$['store']['book'][0]")]`

Use @root, not $, to reach outside the candidate. $ is not defined inside a filter body — [?(@.id===$.trigger.id)] fails the step with $ is not defined.

What does not work

Each of these fails the step outright. The error text below is what the engine returns.

`|` anywhere in the path

| is the concatenation delimiter and is consumed before the string ever reaches JSONPath, so a path containing one is split into fragments and each fragment is parsed separately.

$.users[?(@.role==='admin' || @.role==='moderator')]
→ Unexpected "?" at character 0

There is no way to express OR in a filter. Restructure as two mappings, or move the logic into an Eval step. The same restriction means a literal | cannot appear in a mapped string at all.

Unquoted string literals

A bare word in a comparison is parsed as a variable name.

$.users[?(@.role===admin)]
→ admin is not defined

Quote it: [?(@.role==='admin')].

A single `=`

$.users[?(@.status='active')]
→ Invalid left-hand side in assignment

Use === or ==.

Type selectors

@string(), @number(), @integer(), @boolean(), @array(), @object(), @null(), @scalar() and @undefined() all fail to parse in this build.

$.data[?(@string())]
→ Unexpected "@" at character 1

typeof @.v === 'number' and typeof @ === 'string' are the working substitutes. For array and object tests, use an Eval step — Array.isArray is not in scope inside a filter.

Aggregation functions

@min(), @max(), @avg(), @sum() and .max() do not exist.

$.products[?(@.price===@min(@..price))]
→ Expected expression after === at character 13

Aggregate in an Eval step.

`[*]` inside a filter body

$.agents[?(@.expertise[*]==='api')]
→ Unexpected "*" at character 15

Use @.expertise.indexOf('api')>-1.

A bare `@` on its own

@ must be followed by a property, or wrapped in typeof.

$.products[?(@)]        → Unexpected "@" at character 0
$.data[?(@==='text')]   → Unexpected "@" at character 0

Host globals

String, Number, Array, Object and friends are not in scope inside a filter body.

$.users[?(String(@property).indexOf('0')>-1)]   → String is not defined
$.data[?(Array.isArray(@.v))]                   → Array is not defined

Methods on the candidate’s own values are fine — it is only the global constructors that are missing.

A filter that reads a property missing from any candidate fails the whole step, rather than skipping that candidate. If one row in a list has no address, then [?(@.address.city==='Boston')] errors with Cannot read properties of undefined (reading 'city') and the run ends. Guard it: [?(@.address && @.address.city==='Boston')].

Errors you will see

There is no separate validation pass. An unresolvable mapping fails the step with failed to resolve jPath and the message from the engine. The messages come from JSONPath and its expression parser, so they read like JavaScript errors:

Message	Cause
`Unexpected "?" at character 0`	a `\|` inside the path split the filter apart
`Unexpected "@" at character 1`	a type selector such as `@string()`
`Unexpected "*" at character N`	`[*]` inside a filter body
`<word> is not defined`	an unquoted string literal, or `$` used inside a filter
`Invalid left-hand side in assignment`	`=` where `===` was meant
`Cannot read properties of undefined (reading '<key>')`	a filter reached through a property one candidate does not have
`Expected expression after === at character N`	an aggregation function such as `@min()`

A path that simply matches nothing is not an error — see the two failure modes.

Next steps

Concatenation

Building strings with |

Examples

Worked mappings, run end to end

Eval Step

Where logic JSONPath cannot express belongs

Overview

Data sources, path shapes, failure modes

Get Started

Spaces

Meetings

Forms

Assistants

Collaboration

Flows

Account Management

Advanced

JSONPath

JSONPath

Selectors

Bracket notation

Slices

Recursive descent

Parent and property operators

Filters

Context variables

What does not work

`|` anywhere in the path

Unquoted string literals

A single `=`

Type selectors

Aggregation functions

`[*]` inside a filter body

A bare `@` on its own

Host globals

Errors you will see

Next steps

Concatenation

Examples

Eval Step

Overview

​JSONPath

​Selectors

​Bracket notation

​Slices

​Recursive descent

​Parent and property operators

​Filters

​Context variables

​What does not work

​| anywhere in the path

​Unquoted string literals

​A single =

​Type selectors

​Aggregation functions

​[*] inside a filter body

​A bare @ on its own

​Host globals

​Errors you will see

​Next steps

Concatenation

Examples

Eval Step

Overview

JSONPath

Selectors

Bracket notation

Slices

Recursive descent

Parent and property operators

Filters

Context variables

What does not work

`|` anywhere in the path

Unquoted string literals

A single `=`

Type selectors

Aggregation functions

`[*]` inside a filter body

A bare `@` on its own

Host globals

Errors you will see

Next steps