# JSON Path

Select values from a JSON document with a
[JSONPath](https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html) expression. Use it to
extract nested fields, array items, or filtered matches without reshaping the payload. Paths can use dot notation,
bracket notation, or a mix of both. JSON Path lives in the **Data format** category of the `fx` menu.

For aggregations, mapping, or building a new JSON shape, use [JSONata](../jsonata/) instead.

## Parameters

| Parameter | Type    | Required | Default | Description                                                                                                                                                     |
| --------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input     | string  | yes      | —       | JSON document as a string. Must parse as JSON.                                                                                                                  |
| Path      | string  | yes      | `""`    | JSONPath expression to evaluate. See the [JSONPath documentation](https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html) for syntax. |
| Flatten   | boolean | no       | `false` | Flatten nested arrays in the result into a single-dimension array.                                                                                              |
| Wrap      | boolean | no       | `true`  | Wrap results in an array. When off, a single non-array match is returned unwrapped, and no match returns empty. Multiple matches still return an array.         |
| Quotes    | boolean | no       | `true`  | Keep JSON quotes around a string result. Turn off when you need the raw string in another expression.                                                           |
| Eval      | boolean | no       | `true`  | Allow JavaScript evaluation in the path. Filter expressions such as `[?(@.price < 10)]` require this. Turn off when the path comes from untrusted input.        |

`Input` is the primary JSON document (previous step output or a literal). **Flatten**, **Wrap**, **Quotes**, and
**Eval** are toggles on the function card.

## Returned value

| Type     | Description                                                                                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string` | The query result, serialized as JSON. With Wrap on (the default), this is a JSON array string such as `["alice.martin@exemple.fr"]`. With Wrap off, a single string includes JSON quotes unless Quotes is off. |

## Limitations

- Input and Path must be strings. Non-string Input raises `Invalid input`. Non-string Path raises `Invalid path`.
- Input must be valid JSON. Malformed JSON raises a parse error.
- Filter expressions such as `[?(@.field)]` require Eval to be on. With Eval off they raise
  `Eval [?(expr)] prevented in JSONPath expression.`
- With Wrap off, no match returns an empty value. With Wrap on, no match typically returns `[]`.
- Quotes only strips wrapping quotes when the serialized result is a JSON string (a single string match with Wrap off).
  Array results such as `["red"]` are unchanged.
- Large integer values are preserved when the result is stringified (for example, BSON-style IDs).

:::tip
Leave **Eval** on for filter expressions such as `[?(@.price < 10)]`. Turn it off when **Path** comes from untrusted
input.
:::

## Examples

<details>
<summary>Select a field</summary>

Extract a nested field from a JSON document — the most common JSON Path use in a flow. Pass the previous step’s JSON
into **Input**, set **Path** to the field, and leave **Wrap** on so the result is a JSON array.

1. Set **Input** to the JSON from the previous step (or a literal document).
2. Set **Path** to the field to extract. Paste:

   ```text title="Path"
   $.email
   ```

3. Leave **Wrap** on and confirm **Output value** shows the match in a JSON array.

   <div class="docs-screenshot-compact">

   ![JSON Path extracting the email field into a wrapped array](./assets/select-a-field.png)

   </div>

</details>

<details>
<summary>Return a raw string</summary>

Turn **Wrap** and **Quotes** off when you need the matched string without an array or JSON quotes. Use this when the
result feeds another expression that should not escape quotes.

1. Set **Input** to a JSON document that includes the field to extract.
2. Set **Path** to the field. Paste:

   ```text title="Path"
   $.email
   ```

3. Turn **Wrap** off and **Quotes** off.
4. Confirm **Output value** is the bare string (no array brackets, no JSON quotes).

</details>

<details>
<summary>Filter matching items</summary>

Use a filter expression in **Path** to keep array items that match a condition. **Eval** must stay on. The default Wrap
setting returns the matching values as a JSON array. See the
[JSONPath documentation](https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html) for filter
syntax.

1. Set **Input** to a JSON document that contains the array to filter.
2. Keep **Eval** on. Set **Path** to the filter expression. Paste:

   ```text title="Path"
   $.store.book[?(@.price < 10)].title
   ```

3. Confirm **Output value** lists the matching titles as a JSON array.

</details>

<details>
<summary>Flatten nested arrays</summary>

Turn **Flatten** on when the path returns arrays inside arrays and you need a single list of values.

1. Set **Input** to a JSON document with nested arrays.
2. Set **Path** to the nested array path. Paste:

   ```text title="Path"
   $.groups[*].tags
   ```

3. Turn **Flatten** on.
4. Confirm **Output value** is a single-dimension JSON array (for example `["a","b","c"]` instead of
   `[["a","b"],["c"]]`).

</details>