{jsonpath:string:query:attr:delimiter}

Description

Runs a JSONPath query against a JSON value and returns the matching data. The first parameter is either a JSON variable name defined earlier on the page with definejson, or a literal JSON string (for example one loaded with include from a remote API). The second parameter is the JSONPath query (paths like dollar dot data, array indexes, wildcards, and filter expressions). By default only the first matching value is returned; pass a delimiter as the fourth parameter to return all matches joined by it (note: the delimiter is appended after every match, including the last, so a trailing delimiter remains). The optional third parameter picks one attribute from each matched object, or the literal JSON to return the whole matched structure as a JSON string, or varjson to store each match in a temporary JSON variable and return its name. A query that matches nothing, an invalid JSONPath, or invalid JSON all return an empty string without raising an error.

Parameters

string required

The JSON to query - either a JSON variable name defined earlier on the page with definejson, or a literal JSON string (for example one loaded with include from a remote API).

query required

The JSONPath query to evaluate against the JSON, for example $.data, an array index like $.nums[1], a wildcard $.items[*].name, or a filter $.data[?(@.email=="a@x.cz")].status.

attr optional

Optional. How each matched element is rendered. Leave empty to return the matched scalar value (objects/arrays come back as JSON). Give an object key to return that attribute from each match. Use JSON to return the whole matched structure as a JSON string. Use varjson to store each match in a temporary JSON variable and return its name (for a follow-up jsonpath call).

delimiter optional

Optional. By default only the first matching value is returned. If you give a delimiter, every match is returned with the delimiter appended after each one (including after the last match, so the result ends with a trailing delimiter).

Examples

test[{jsonpath:{"data":[{"email":"a@x.cz","status":1},{"email":"b@x.cz","status":3}]}:$.data[?(@.email=="b@x.cz")].status}]

Expected[3]

Actual[3]

A filter [?(@.email=="b@x.cz")] keeps only objects whose email equals b@x.cz, then .status reads that field. This is the typical lookup-by-key pattern.

test[{jsonpath:{"city":"Praha"}:$.nope}]

Expected[]

Actual[]

A query that matches nothing returns empty. Invalid JSON and an invalid JSONPath behave the same way: jsonpath returns an empty string and does not raise an error.

test[{jsonpath:{"data":[{"email":"a@x.cz","status":1},{"email":"b@x.cz","status":3}]}:$.data[?(@.email=="b@x.cz")]:status}]

Expected[3]

Actual[3]

Here the query returns the whole matched object and the third parameter (attr) selects the status attribute from it. Equivalent to putting .status in the query.

test[{jsonpath:{"nums":[10,20,30]}:$.nums[1]}]

Expected[20]

Actual[20]

Array indexes are zero-based, so $.nums[1] is the second element.

test[{definejson:JPVcfg:{"site":"AA","limit":10}}{jsonpath:JPVcfg:$.limit}]

Expected[10]

Actual[10]

When the first parameter is a name defined earlier with definejson, jsonpath reads that stored JSON. definejson must run before jsonpath on the same page. Define and read are kept in one expression here so the example is self-contained; the variable name JPVcfg is unique to this example to avoid clashing with other examples on the page.

test[{jsonpath:{"city":"Praha","zip":"11000"}:$.city}]

Expected[Praha]

Actual[Praha]

The first parameter is a literal JSON string, the second is the JSONPath query. $.city selects the city value. Brackets are added only to make the output boundary visible.

virtual

{definejson:Subs:{include:https#://api.example.org/lists/2/subscribers:GET:{jsonasoc:Content-Type:application/json}}}{jsonpath:Subs:$.data[?(@.email=="editor@example.org")].status}

Expected(a status code such as 1, depending on the API response)

The production pattern: definejson loads and parses a remote JSON API response (with include) into a variable, then jsonpath looks up one record by email and reads its status. Marked illustrative because the output depends on a live API. The status code is usually mapped to a label with ifeq, for example {ifeq:{jsonpath:Subs:...}:1:subscribed:2:unsubscribed:unknown}.

test[{jsonpath:{"items":[{"n":"Ada"},{"n":"Boris"}]}:$.items[*].n::, }]

Expected[Ada, Boris, ]

Actual[Ada, Boris, ]

The fourth parameter is the delimiter (here a comma and a space). All matches are returned, but the delimiter is appended after EVERY match, including the last, so the result ends with a trailing comma-space.

test[{jsonpath:{"data":[{"email":"a@x.cz","status":1},{"email":"b@x.cz","status":3}]}:$.data[?(@.email=="b@x.cz")]:JSON}]

Expected[{"email":"b@x.cz","status":3}]

Actual[{"email":"b@x.cz","status":3}]

With the third parameter set to JSON, the whole matched structure is returned as a JSON string instead of a scalar value.

test[{jsonpath:{"items":[{"n":"Ada"},{"n":"Boris"}]}:$.items[*].n}]

Expected[Ada]

Actual[Ada]

The query $.items[*].n matches every name, but with no delimiter (fourth parameter) jsonpath returns only the first match. Add a delimiter to get them all - see the next example.

← All expressions