JSONPath
JSONPath is a small query language for pointing at one specific part of a JSON document — a field, an array item, a number, whatever you need. In Routix Dash, a JSONPath transformer reads a value out of parsed JSON and passes it on as the result of that transformer in the chain.
You'll find JSONPath in:
- Actions / Transformers pipe on an HTTP data source or HTTP destination — after (or between) HTTP requests in that list.
- Data source transformers — MQTT, WebSocket, and Timer: reshape incoming data before it's stored.
- Data piece transformers — reshape the root source value for this data piece.
- Component transformers — pick out exactly what a component should show.
- Tap actions — extract or reshape data mid-action, for example before sending it to a destination.
In any of those chains, tap a row to edit it, drag the handle to reorder, and swipe right to left to delete a transformer or action.
The syntax follows the RFC 9535 JSONPath standard. This page covers what you'll use day to day.
Quick reference
| Goal | Example |
|---|---|
| Root | $ |
| Child field | $.a, $.a.b |
| Field name with special characters | $['a-b'] |
| Array item | $.arr[0], $.arr[-1] |
| Search at any depth | $..price (every price field anywhere), or * for one level (per RFC 9535) |
| Several matches | e.g. $..price — use "first item" (see below), or write a more specific path |
| Tap actions | $.value… (live), $.raw… (fixed for the tap), $.ctx… (shared), $.transformed… (tap only, fixed for the tap), $.env…, $.vars… |
| Data transformers (source, data piece, or component) | $.value… for data, $.raw… for the start of the chain, $.ctx… for extras, $.env… and $.vars… for variables; there's no $.transformed |
| Connection error in transformers | $.ctx.error.message, $.ctx.error.kind, $.ctx.error.statusCode |
| MQTT details | e.g. $.ctx.transport.topic, $.ctx.transport.receivedAt (see MQTT: ctx.transport) |
| HTTP | $.ctx.transport.responseTime, $.ctx.transport.statusCode, $.ctx.transport.url, $.ctx.transport.requestHeaders, $.ctx.transport.responseHeaders (see HTTP: ctx.transport) |
| WebSocket | $.ctx.transport.event, $.ctx.transport.mode (see WebSocket: ctx.transport) |
| Timer tick | $.ctx.transport.reason, $.ctx.transport.intervalMs (see Timer: ctx.transport) |
| ENV variable | $.env.my_key (when the path uses env; see ENV variables) |
Runtime vars |
$.vars.my_key (see Runtime vars) |
| Custom screen | $.params.room — values passed when the screen opened |
| Component look (read) | $.comp.visible, $.components.label1.value — on a data piece or component only; see Lua and JavaScript |
Where it runs
- Data transformers:
$is a map with the namesvalue,raw,ctx,env, andvars. The current data is under$.valueand can be an object, array, number, or text. - Tap actions:
$has the same names plustransformed. - On a custom screen, both also have
params. - On a data piece or component (not a data source or HTTP list), you can also read
$.comp…and$.components.<id>…. JSONPath cannot change them — use Lua or JavaScript. - If incoming text was meant to be JSON but isn't, decoding fails before JSONPath runs.
- The text you type is a JSONPath string, which is a different language from the in-app expression syntax.
The JSON document and $
- A path almost always starts with
$, meaning the root of the JSON you're querying. - After that, add segments separated by
.(a dot), or use brackets[…]for names and positions.
Examples (generic JSON):
$.name— the top-level fieldname$.user.email— theemailfield insideuser$.items[0]— the first item in theitemsarray (counting from 0)$.items[-1]— the last item initems(a negative index counts from the end)$['a-b']— a field whose name isn't a simple word (for example it has a hyphen) — use a quoted name inside the brackets$.store.book[2].price— thepriceof the third book in thestore.bookarray
Those examples show JSONPath syntax on a generic document. In a data transformer, data paths start with $.value — so a generic $.name becomes $.value.name.
In data transformers vs tap actions: value, raw, ctx, transformed
The JSON document your JSONPath transformer queries depends on where the transformer runs.
- Data transformer (on a data source, a data piece, or a component):
$.value…reads the data.$.raw…reads the data at the start of the chain.$.ctx…reads extras.$.env…and$.vars…read variables. There's no$.transformedin data transformers. - Tap action: the same names plus
transformed. To read an app-wide variable, start the path with$.env— for example$.env.my_key.
In a tap action, you can use $.value, $.raw, $.ctx, $.transformed, $.env, and $.vars ($.transformed is tap-only):
$.value— the current data you're working with. In a multi-action tap it changes as each action runs.$.raw— a fixed snapshot for the whole tap: the source's data right after its own transformers ran.$.transformed— tap only. A fixed snapshot of whatever the component was showing when you tapped it. Stays the same even if$.valueis updated by a later action.$.ctx— a shared set of details for passing data between actions, or carrying connection details. Extra keys such as$.ctx.unitor$.ctx.replywork the same way.$.env.my_key— an app-wide variable, when the path starts with$.env.$.vars.my_key— a value from the runtimevarsstore.$.params.room— on a custom screen only: a value passed when the screen opened.$.comp…/$.components.<id>…— on a data piece or component only. How that component (or another, by ID) looks right now. JSONPath cannot change them — use Lua or JavaScript.
Examples (tap action):
$.value.temperature$.value.sensors[0].id$.raw— the whole fixed raw branch$.transformed.someField— read from the frozen tap-start value, even while$.valuemay already be different
Data transformer examples:
$.value.temperature— readstemperaturefrom the current data.- For data like
{"value": 7},$.value.valuereads that field and returns7. $.ctx.error.message— reads the current connection error's message.$.raw.temperature— readstemperaturefrom the data at the start of the chain, even after an earlier transformer narrowed$.value.
Reading $.ctx.error (or one of its fields) doesn't clear the error — use a Lua or JavaScript transformer if the chain should mark it as handled. A bad JSONPath is a transformer mistake, separate from ctx.error, and it stops the rest of the current transformer chain.
JSONPath only sees the names above. To read a different data source by name, use a Simple expression, Lua, or JavaScript transformer with source_value("Name") / source_raw("Name") (or JavaScript sourceValue / sourceRaw).
See also Expressions, Lua, JavaScript, and Expressions in editors — they expose the same names with different syntax.
MQTT: ctx.transport
For an MQTT data source, when ctx.transport is present, it describes the most recently received message. $.ctx.transport is a JSON object describing that message alongside the main data, which stays at $.value.
Typical fields:
topic— the MQTT topicpayload— the same decoded body as the currentvalueqos— the QoS level (0–2)retain— whether the message was sent with the retain flagprotocolVersion— which MQTT version the connection usesreceivedAt— when it arrived, in ISO 8601 form, UTC (…Z)
MQTT 5 may add retainAsPublished, contentType, userProperties, responseTopic, correlationData (base64 text), messageExpiryInterval, and similar fields when the broker provides them.
Examples: $.ctx.transport.topic, $.ctx.transport.receivedAt, or fields under $.value for the message body.
HTTP: ctx.transport
For an HTTP data source or destination, and for a tap HTTP request, $.ctx.transport describes the last HTTP request in that list. Body data stays under $.value. Every HTTP request overwrites transport.
Typical fields: method, url, requestHeaders, statusCode, responseTime (milliseconds), contentType, charset, responseHeaders, receivedAt. Header names are lowercase — for example $.ctx.transport.responseHeaders['content-type'] or $.ctx.transport.requestHeaders['authorization'].
Example: $.ctx.transport.responseTime to show how long the request took.
WebSocket: ctx.transport
For a WebSocket data source, $.ctx.transport describes the most recently received message. Body data stays under $.value.
Typical fields: mode (websocket, sse, or socket.io), event, payload, url, receivedAt. On SSE, id when the server sent a last-event id.
Examples: $.ctx.transport.event, $.ctx.transport.mode.
Timer: ctx.transport
For a Timer data source, $.ctx.transport describes the last tick: reason (interval, trigger, defaultValue, or peer), intervalMs, receivedAt.
Wildcards, search, and recursive descent
*— "any key" or "any array position" for one level (wherever a wildcard is allowed there)...(two dots, recursive descent) — search below the current point, at any depth.- Example:
$..price— everypricefield anywhere in the document.
- Example:
Use wildcards and .. when the nesting depth or exact path can vary.
Filtering with ? and @
A filter keeps only the items that pass a test. Inside a filter, @ refers to the item currently being tested.
Filter syntax follows RFC 9535. A filter that's wrong, or too narrow, matches nothing — and a JSONPath that matches nothing fails (see Errors and empty results).
Tip: start with a path without a filter, check that you're looking at the right branch of the JSON, then add a filter that matches the shape of each item in the list.
Slices
A slice takes a sub-range of an array (start, end, and step follow RFC 9535). Check the result against real data to be sure of your indexes and end points.
Results and "first item"
A JSONPath query can return more than one match — for example, several price fields from $..price.
In the editor you can turn on "use first item from results":
- On (the usual default): if there are several matches, the transformer uses the first one as its output.
- Off: the output may be a list of every matched value.
If you expect a single value, either write a path that's already unique, or leave "first item" turned on.
In a chain, the transformer's output becomes the new value for whatever comes next.
Errors and empty results
- Invalid JSONPath text (a typo, mismatched brackets, an unclosed quote) — the path can't be used until it's fixed.
- A valid path with no match (wrong field name, an index out of range, a filter that's too narrow) — the transformer fails with JSONPath matched no values and the rest of the chain stops, like any other transformer error.
- The input looks like JSON but isn't valid (a missing brace, a trailing comma, single quotes) — the value stays text, and the error starts with The value is not valid JSON and the place where reading stopped. The data source, data piece and component settings also show Malformed JSON. Using the value as text. above Add.... Fix the data earlier in the chain, or fix the source.
The same JSONPath text can behave differently depending on the shape of the data it's given. If you're not sure, look at the actual JSON the transformer receives, then build the path from the root down.