# JSON

Read, set, merge and pick fields in JSON.

## Do things in JSON

Add a **JSON** step and choose an **Operation**. Choose the row to see the fields of each.

- [JSON Operation](https://docs.gorunner.io/apps/json#fields-f-convert): Parse (text → data) · Stringify (data → text) · Get value at path · Set value at path · Merge (shallow) · Merge (deep) · Pick fields · Omit fields · Validate against schema

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

**What changed in version 2?**

New steps use version 2.0.0. A step made before keeps 1.0.0 and works as it always has. The step’s panel shows its version at the top right. On an older step it reads **v1.0.0 · 2.0.0 available**: press it to choose the version.

In 2.0.0: **Stringify (data → text)** writes `<`, `>` and `&` as they are. **Get value at path** reads the **Object** field, like **Set value at path**. Version 1.0.0 escapes those characters and reads **JSON Text**.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, JSON is `pieceId: "json"` with `actionId: "convert"`, set by `operation`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It computes from its inputs only (`pure`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### JSON › JSON Operation

Parse, stringify, read/set paths, merge objects, or pick/omit fields.

### Parse (text → data)

- **JSON Text · Required**: The text to read as data, such as {"name":"Ann","age":30}. Data that is already structured (such as {{steps.parse_xml.result}}) is accepted as-is.

### Stringify (data → text)

- **Object · Required**: The object to read from or change. Text holding JSON (such as {{steps.http.body}}) is read as data.
- **Pretty print · Optional**: Turn on to space out the text over multiple lines so it is easier to read. Off by default.

### Get value at path

- **Object · Required**: The object to read from or change. Text holding JSON (such as {{steps.http.body}}) is read as data.
- **Path · Optional**: Location of the value inside the data, using dots for nesting, such as data.items[0].name. Required when setting a value; leave blank when reading to get the whole object.

### Set value at path

- **Object · Required**: The object to read from or change. Text holding JSON (such as {{steps.http.body}}) is read as data.
- **Path · Optional**: Location of the value inside the data, using dots for nesting, such as data.items[0].name. Required when setting a value; leave blank when reading to get the whole object.
- **Value · Optional**: Value to set at the path, written as JSON, so text needs quotes ("active"), while numbers, true/false, objects and lists are written plainly (42, true, {"a":1}).

### Merge (shallow) and Merge (deep)

- **Object · Required**: The object to read from or change. Text holding JSON (such as {{steps.http.body}}) is read as data.
- **Merge With · Required**: Second object; its keys win on conflict.

### Pick fields and Omit fields

- **Object · Required**: The object to read from or change. Text holding JSON (such as {{steps.http.body}}) is read as data.
- **Fields · Required**: List of top-level field names, such as ["id","name"].

### Validate against schema

- **Object · Required**: The object to read from or change. Text holding JSON (such as {{steps.http.body}}) is read as data.
- **JSON Schema · Required**: JSON Schema (draft 2020-12) to validate the object against.

Source: https://docs.gorunner.io/apps/json