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:

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


The JSON document and $

Examples (generic JSON):

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.

In a tap action, you can use $.value, $.raw, $.ctx, $.transformed, $.env, and $.vars ($.transformed is tap-only):

Examples (tap action):

Data transformer examples:

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:

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

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

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


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.