---
title: "json_path | Speedscale Docs"
description: "Extract a JSON value by path with the json_path transform in Speedscale, let downstream transforms rewrite it, then re-insert the new value at the same location with type preservation."
canonical: "https://docs.speedscale.com/guides/transformation/transforms/json_path/"
---

[Documentation index](https://docs.speedscale.com/guides/llms.txt) | [Markdown](https://docs.speedscale.com/guides/transformation/transforms/json_path/index.md) | [Canonical page](https://docs.speedscale.com/guides/transformation/transforms/json_path/)

# json\_path

The `json_path` transform extracts a value from a JSON document using a JSONPath expression and acts as a window onto that value for the rest of the chain. Downstream transforms see only the extracted scalar; when they're done, `json_path` writes the new value back into the same location of the original document, preserving JSON types where possible.

It is the most common entry point for transforms that operate on JSON bodies — almost every chain that touches a JSON field starts with `req_body()` or `res_body()` followed by `json_path`.

*   **Transform type name (config/API):** `json_path`
*   **Shorthand format:** `json_path(path=...)`
*   **Path syntax:** [gjson path syntax](https://github.com/tidwall/gjson#path-syntax). Not all features of every JSONPath spec are supported — when in doubt, test against the gjson playground.

<a id="quick-start"></a>

## Quick Start

Extract a simple field:

```json
"type": "json_path",
"config": {
    "path": "client_secret"
}
```

Extract a nested field, then replace it with a random value:

```text
req_body() → json_path(path="user.id") → rand_string(pattern="[0-9]{8}")
```

The chain extracts `user.id`, hands the value to `rand_string`, then writes the new digits back into `user.id` in the original body.

<a id="how-it-works"></a>

## How It Works

The transform runs in two phases as a bookend around the rest of the chain.

1.  **First phase** — parse the JSON document, look up the configured `path`, and return the value at that path as a plain scalar so downstream transforms see just the inner value. The original document bytes are remembered for re-insertion.
2.  **Second phase** — take whatever the downstream chain produced, coerce it to a JSON-compatible type matching the original value's type (see [Type Preservation](https://docs.speedscale.com/guides/transformation/transforms/json_path/#type-preservation)), and write it back into the original document at the same path.

```text
input:  {"foo": {"bar": "baz"}}
        └─ 1st phase, path="foo.bar": extracted = "baz", remembered = full body
        └─ downstream transforms see "baz" and produce, say, "bam"
        └─ 2nd phase: writes "bam" back into foo.bar
output: {"foo": {"bar": "bam"}}
```

<a id="path-syntax"></a>

### Path Syntax

Paths follow gjson's syntax. The most common forms:

| Form | Example | Meaning |
| --- | --- | --- |
| Dot path | `foo.bar` | Nested object access. |
| Array index | `product.0` | Element 0 of an array. |
| Wildcard (root array) | `#.travelers.#.name` | Iterate every entry of a top-level array. See [Root-Array Wildcards](https://docs.speedscale.com/guides/transformation/transforms/json_path/#root-array-wildcards). |

For advanced features (filters, queries, modifiers), consult the [gjson path syntax docs](https://github.com/tidwall/gjson#path-syntax). Not every feature there round-trips cleanly through re-insertion — stick to dot/index paths and root-array wildcards for production chains.

<a id="type-preservation"></a>

### Type Preservation

Re-insertion tries to keep the JSON type of the original value. The downstream chain produces text bytes; the transform coerces those bytes back to the original JSON type:

| Original type | Coercion of the new value |
| --- | --- |
| String | Used as-is (written as a JSON string). |
| Number | Parsed as float. If parsing fails, the field is written as `0` rather than changing the field's JSON type. |
| Boolean | Parsed as bool. If parsing fails, the value is dropped. |
| Null | The new value is guessed: bool first, then int, then float, then string. |
| JSON object/array | Written raw. |

The fallback to `0` for unparseable numbers is intentional — it keeps the document's shape valid even if a downstream chain emitted nonsense for a numeric field.

<a id="root-array-wildcards"></a>

### Root-Array Wildcards

`gjson` and `sjson` disagree on how to write back into a root-level JSON array using the leading `#` wildcard. `json_path` expands a path like `#.travelers.#.name` against a root-level array by writing the downstream value into every concrete index. Without this expansion the body would be corrupted.

```text
input:  [{"travelers":[{"name":"a"},{"name":"b"}]},{"travelers":[{"name":"c"}]}]
path:   #.travelers.#.name
new:    "*"
output: [{"travelers":[{"name":"*"},{"name":"*"}]},{"travelers":[{"name":"*"}]}]
```

This applies only when the top-level document is a JSON array. For object-rooted documents, use a concrete path.

<a id="missing-paths"></a>

### Missing Paths

What happens when the path doesn't exist depends on `create`:

| `create` | Path missing — first phase | Path missing — second phase |
| --- | --- | --- |
| `true` (default) | Returns an empty token so downstream transforms don't see `nil`. | Treats the downstream output as the new value and inserts it at the path, creating the necessary structure. |
| `false` | Returns the original token with a "path value not found" error; the chain stops working on this token. | Returns the original document unchanged. |

Use `create=false` when you want to _only_ operate on documents that already have the field — useful when the same chain runs on heterogeneous traffic.

<a id="configuration"></a>

## Configuration

```json
"type": "json_path",
"config": {
    "path": "<gjson path>",
    "create": "<boolean>"
}
```

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `path` | **Yes** | — | The gjson path to the value. Missing config fails chain initialization. |
| `create` | No | `true` | If the path is missing, create it at insert time. Set to `false` to skip transformation when the field is not present. |

`path` supports `${{...}}` variable substitution, resolved at runtime against the variable cache. This lets one chain target a dynamically chosen field.

<a id="examples"></a>

## Examples

<a id="example-1--simple-findreplace"></a>

### Example 1 — Simple find/replace

```text
req_body() → json_path(path="client_secret") → constant(value="redacted")
```

*   Input: `{"client_id":"...","client_secret":"<long>"}`
*   Output: `{"client_id":"...","client_secret":"redacted"}`

<a id="example-2--numeric-field-type-preservation"></a>

### Example 2 — Numeric field type preservation

```text
req_body() → json_path(path="user.age") → constant(value="30")
```

*   Input: `{"user":{"age":22}}`
*   Output: `{"user":{"age":30}}` — written as a JSON number, not the string `"30"`.

<a id="example-3--create-a-missing-field"></a>

### Example 3 — Create a missing field

```text
req_body() → json_path(path="foo.bar") → constant(value="bam")
```

*   Input: `{}`
*   Output: `{"foo":{"bar":"bam"}}` — `create=true` (the default) builds the nesting.

<a id="example-4--top-level-array-wildcard"></a>

### Example 4 — Top-level array wildcard

```text
req_body() → json_path(path="#.travelers.#.name") → constant(value="*")
```

*   Input: `[{"travelers":[{"name":"a"},{"name":"b"}]},{"travelers":[{"name":"c"}]}]`
*   Output: `[{"travelers":[{"name":"*"},{"name":"*"}]},{"travelers":[{"name":"*"}]}]`

<a id="example-5--json-inside-json-nested-json_path-chains"></a>

### Example 5 — JSON-inside-JSON (nested json\_path chains)

Some payloads embed a JSON string as the value of an outer JSON field. Stack two `json_path` transforms to drill through:

```text
req_body()
  → json_path(path="operations.0.eventDefinition.payload")   # extract the inner JSON string
  → json_path(path="additionInfo.SLAEventID")                # extract a field from it
  → constant(value="*")
```

*   Input:
    
    ```text
    {"operations":[{"eventDefinition":{"payload":"{\"additionInfo\":{\"SLAEventID\":\"goal:c7d...\"}}"}}]}
    ```
    
*   Output:
    
    ```text
    {"operations":[{"eventDefinition":{"payload":"{\"additionInfo\":{\"SLAEventID\":\"*\"}}"}}]}
    ```
    

The inner `json_path` operates on the string yielded by the outer one; both re-insert in reverse order on the way back up.

<a id="common-misconceptions"></a>

## Common Misconceptions

1.  **"`json_path` only extracts."** It also re-inserts. The chain's tail produces a new value, and `json_path` writes it back at the same path on the way out.
    
2.  **"It writes everything as a string."** No. The original JSON type is preserved on re-insertion when possible — number stays number, bool stays bool, null is guessed.
    
3.  **"It supports full JSONPath spec (RFC 9535) including filters, recursive descent, slicing."** The path syntax is gjson's, which is similar but not identical. Recursive descent (`..`) and complex filter expressions may not round-trip through re-insertion. Use `json_selector` for recursive matching by key/value.
    
4.  **"`create=true` means the chain always succeeds."** It means missing paths get created on insert. The downstream chain still has to produce a value worth inserting. If it produces an empty string, you get an empty value at the path.
    
5.  **"Setting a field to non-numeric text on a number field fails the chain."** It doesn't fail — it writes `0` to preserve the JSON type. If you need the chain to halt instead, validate upstream or use `create=false` and a more specific path.
    

<a id="troubleshooting"></a>

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Chain init: `missing parameter path` | `path` not set | Add `"path": "..."` |
| Token unchanged, "path value not found" error | The path doesn't exist in the input document and `create=false` | Either set `create=true` or fix the path |
| Numeric field becomes `0` | Downstream produced non-numeric text for a number field | Make the upstream transform produce numeric text, or restructure the chain |
| Output JSON has the new value but different formatting (whitespace, key order) | `sjson` rewrites the document on insert | This is expected; downstream consumers should parse JSON, not match byte-for-byte |
| Top-level array path doesn't work with `#` | Targeting a root-level array | Use the `#.field...` form — the transform expands it across all indices |
| Path with advanced gjson features doesn't round-trip | `sjson` doesn't support all `gjson` features for writes | Use a simpler path, or switch to [`json_selector`](https://docs.speedscale.com/guides/transformation/transforms/json_selector/) for recursive matching |

<a id="related-transforms"></a>

## Related Transforms

*   [`json_selector`](https://docs.speedscale.com/guides/transformation/transforms/json_selector/) — match by key/value with optional recursion, useful when the exact path varies between requests.
*   [`xml_path`](https://docs.speedscale.com/guides/transformation/transforms/xml_path/) — the XML counterpart, using XPath.
*   [`regex`](https://docs.speedscale.com/guides/transformation/transforms/regex/) — same two-phase extract/re-insert pattern, but pattern-based rather than JSON-aware.
*   [`smart_replace`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace/) — combine with `json_path` to propagate a value extracted from one field across the entire RRPair.

<a id="advanced-notes"></a>

## Advanced Notes

*   The transform does not require recorded response data.
*   The original document bytes are copied at extract time, so the downstream chain may mutate the extracted token without disturbing the document used for re-insertion.
*   gjson's path syntax is well-documented; sjson's _write_ support is narrower. If you write an advanced path and the re-insertion mangles the document, fall back to a simpler dot path or use `json_selector`.
*   `path` is re-resolved on both the first and second phases against the variable cache, so a `${{var:...}}` reference picks up whichever value is current at each phase.
