Working with JSONPath

JSONPath is a query language for selecting values from JSON. In Wrk, you can use JSONPath in Custom Outputs to turn a value inside an existing Wrk Action output into a named Data Library item for downstream Wrk Actions.

Wrk supports the extended parser from jsonpath-ng.ext. This includes standard paths plus filters, array access, arithmetic, string operations, and named extension functions. The backticks around a named function are part of the expression and must be included.

When to use JSONPath

Use JSONPath when you need to:

• Select a top-level or nested field from a JSON response.
• Select one or more array items or fields inside array items.
• Filter objects by a field value before returning them.
• Calculate values, sort results, split strings, or combine fields without adding another Wrk Action.
• Give a selected value a clear name with a Custom Output.

If you need to process every item in an array as a separate execution, first use Retrieve all items from a JSON array to divide the array. Then use Custom Outputs and JSONPath on the output containing the current item.

JSONPath basics

The root symbol is $. Use a dot followed by a field name to move through an object, and square brackets to access array items or select fields.

Expression	Selects
$	The complete JSON value.
$.name	The name field at the root.
$.user.contact.email	A nested field.
$.items[0]	The first item in an array.
$.items[*]	Every item in an array.
$.items[*].id	The id field from every item.
$.items[0:2]	A slice containing the first two items.
$.field or $['field']	Equivalent field access syntax. Bracket notation is useful for field names with special characters.

Other useful selectors and operators include:

• * selects any field or array item.
• field1, field2 selects either of two named fields. You can also combine paths with |.
• .. searches for descendants below the current node.
• where selects nodes that have a child matching another JSONPath expression.
• this refers to the current object, and named operators can extend the path with a function.

A worked example

Given this JSON:

{
  "customer": {
    "name": "Alex Rivera",
    "contact": {
      "email": "alex@example.com"
    }
  },
  "customers": [
    {"name": "Alex Rivera", "email": "alex@example.com"},
    {"name": "Jordan Lee", "email": "jordan@example.com"}
  ],
  "orders": [
    {"id": "A-100", "status": "paid", "total": 42},
    {"id": "A-101", "status": "pending", "total": 18}
  ]
}

These expressions return the following values:

Expression	Result
$.customer.name	Alex Rivera
$.customer.contact.email	alex@example.com
$.orders[*].id	["A-100", "A-101"]
$.orders[0].total	42
$.orders[?status = 'paid'].id	A-100
$.orders[?status = 'paid'].total	42

Expressions that match multiple values return multiple results. When you use one in a Custom Output, check the test result and choose the output type and array behavior that match what the downstream Wrk Action expects.

JSONPath NG filters and operators

The extended parser supports filters and common operators for more advanced selection.

Filters

Filter an array with a condition inside [?...]:

With the sample JSON above, each expression returns the matching order as an array:

Expression	Output
$.orders[?status = 'paid']	[{"id": "A-100", "status": "paid", "total": 42}]
$.orders[?total > 20]	[{"id": "A-100", "status": "paid", "total": 42}]
$.orders[?status = 'paid' & total > 20]	[{"id": "A-100", "status": "paid", "total": 42}]

Supported comparisons include equality (= or ==), not equal (!=), greater than (>), greater than or equal to (>=), less than (<), less than or equal to (<=), and regular-expression matching (=~). For example:

Expression	Output
$.customers[?name =~ 'Alex']	[{"name": "Alex Rivera", "email": "alex@example.com"}]

Properties can be compared only with static values. When using =~, the filtered array must contain only objects or strings; integers, booleans, and null values are not supported.

Select values from different places

You can combine paths when you need more than one value, or search through a customer object when you know the field name but not exactly where it is nested:

Expression	What it does	Output
$.customer.name | $.customer.contact.email	Gets the customer's name and email.	["Alex Rivera", "alex@example.com"]
$.customer..email	Finds any email fields anywhere inside the customer object.	["alex@example.com"]

If the customer object contains more than one matching email field, the result includes each matching value in the array.

JSONPath NG extension functions

The examples below use jsonpath-ng.ext. Named functions use backticks.

Function or operation	Example	Output	Use it to
len	$.orders.`len`	2	Return the number of items or keys in a collection.
keys	$.customer.`keys`	["name", "contact"]	Return the keys in an object.
str()	$.customer.`str()`	"{'name': 'Alex Rivera', 'contact': {'email': 'alex@example.com'}}"	Convert a value to a string.
sub	$.customer.name.`sub(/Rivera/, 'R.')`	Alex R.	Replace text that matches a regular expression.
split	$.customer.name.`split(' ', *, -1)`	["Alex", "Rivera"]	Split a string into segments. Use the form split(sep, segment, maxsplit).
sorted	$.orders[/total].id	["A-101", "A-100"]	Sort orders by total, then return their IDs. Use / for ascending and \ for descending sort keys.
Arithmetic	$.orders[0].total * 1.13	47.46	Apply arithmetic to numeric values.
String joins	$.customer.name + ' (' + $.customer.contact.email + ')'	Alex Rivera (alex@example.com)	Combine values and literal strings.

You can combine these features. For example, this expression returns the total of paid orders multiplied by a tax rate:

Expression	Output
$.orders[?status = 'paid'].total * 1.13	[47.46]

Use the jsonpath-ng extended parser documentation for the complete expression grammar and function behavior. Wrk evaluates these expressions against the selected source output when the Custom Output is run.

Configure JSONPath in a Custom Output

1. Run the Wrk Action test so the output you want to inspect is available.
2. Expand the JSON output in Test Results.
3. Double-click a field to create a Custom Output for that field, or select the + control to create outputs for all available fields.
4. Review the generated Custom Output name, source output, and JSONPath expression.
5. Edit the JSONPath when you need a nested value, a filter, or another JSONPath NG expression.
6. Use the resulting named values from the Data Library in downstream Wrk Action inputs.

For Text (short) and Text (long) Custom Outputs, the JSONPath identifies the value to extract from the selected source output. For example, $.name selects a top-level name, while $.customer.contact.email selects a nested email address. For a source output that is already a simple value, you can leave the JSONPath empty and use the source value directly.

Troubleshoot JSONPath expressions

• No value is returned: Confirm that the selected source output contains JSON and that the path matches its shape. Start with $ and add one field at a time.
• Several values are returned: The path probably matches an array or multiple objects. Use an array index, a filter, or an output configuration that accepts an array.
• A function is not recognized: Confirm that the expression uses the extended syntax and includes the backticks around named functions such as `len` or `str()`.
• A downstream input has the wrong type: Inspect the test result and choose a Custom Output field type that matches the extracted value.

Related resources

• Custom Outputs: create named outputs from source outputs with JSONPath.
• Working with JSON: choose between Custom Outputs, array division, and JSON SQL actions.
• Retrieve values from JSON: action-specific inputs, outputs, and outcomes for the JSON extraction Wrk Action.
• Retrieve all items from a JSON array: divide array items for parallel processing.