# Parse JSON

> Break one block of text into separate fields, so later steps can pick out the values inside it.

**Parse JSON** breaks one block of text into separate fields, so each value becomes something later steps can pick from. Use it when data arrives as one long block and you need one value inside it, like the customer's name.

> Dock: Data · Convert · Takes: a block of text · Returns: separate fields

**Keyboard shortcut:** `t+p`

## How to tell you need it

Open the earlier step's result. Look for a value sitting inside one long line of text wrapped in braces and quote marks. If the data picker offers you that whole line but not the name inside it, this is the step that opens it up.

It usually comes from one of four places. A webhook that sent its data as text, an app that answered with text rather than named fields, a database column holding JSON, or a `.json` file you have just read.

## Setting it up

1. Press `t+p`, or open **Tools → Data → Convert** in the dock and select **Parse JSON**.
2. In the **Input** field, select the data reference that contains your JSON string (for example, the response body from a previous HTTP Request step).
3. Save the step.

Glow detects the structure of the parsed JSON automatically. Each field then appears as a selectable output in the data reference picker for downstream steps.

## What it passes on

Every value inside becomes its own field on the step, read with the step's own
number in front — `4` in the examples below. Nothing is wrapped.

- **A record inside a record** is reached with another dot: `{{ 4.customer.name }}`.
- **A list** uses the item's position as the next dot, counting from zero, so
  `{{ 4.items.0.sku }}` is the first. Square brackets such as `items[0]` are not
  recognised.
- **Deeper than that** follows the same pattern all the way down:
  `{{ 4.results.2.metadata.tags.0 }}`.

## Examples to copy

### Reading an app's answer

Suppose an HTTP Request step calls `https://api.example.com/orders/12345` and returns the following response body as a string:

```json
{
  "order_id": 12345,
  "customer": {
    "name": "Acme Corp",
    "email": "orders@acme.com"
  },
  "items": [
    { "sku": "WIDGET-A", "quantity": 10 },
    { "sku": "WIDGET-B", "quantity": 5 }
  ],
  "total": 249.99
}
```

Say the Parse JSON step is step 4. Each value inside is then its own field, read with this step's number in front:

| Reference                  | Value               |
| -------------------------- | ------------------- |
| `{{ 4.order_id }}`         | `12345`             |
| `{{ 4.customer.name }}`    | `"Acme Corp"`       |
| `{{ 4.customer.email }}`   | `"orders@acme.com"` |
| `{{ 4.items.0.sku }}`      | `"WIDGET-A"`        |
| `{{ 4.items.0.quantity }}` | `10`                |
| `{{ 4.items.1.sku }}`      | `"WIDGET-B"`        |
| `{{ 4.total }}`            | `249.99`            |

You can now use `{{ 4.customer.name }}` in a Slack message step, or `{{ 4.total }}` in a Conditions step.

The data picker shows these as `customer.name` and `total`, without the step number. That is the label, not the reference. Pick the value from the picker and Glow inserts the full form for you.

## Limits

### When the text is malformed

If the text is not properly formed JSON, the step fails and the error names what
it choked on. Open the earlier step's **Executions** tab and read the raw value —
that is almost always quicker than guessing which character is wrong.

Where the text comes from a system you do not control and is reliably malformed,
put a [Code editor](/build/action-steps/code-execution) step in front to tidy it
first.

### When nothing arrives

An empty input produces no output, so a later step reading one of these fields
finds nothing there and fails. Where the source sometimes sends nothing, put a
[Conditions](/build/action-steps/conditions) step in front testing the input with
**is not empty**.

### When it is very large

A very large piece of JSON takes the step longer to read. If you only need a few fields out of it, pull those out with a [Code editor](/build/action-steps/code-execution) step first.

> **Escaped characters need no work from you.** A string full of `\"` and `\n`
> comes out with those turned back into quote marks and line breaks. There is
> nothing to clean up first.

## What's Next?

- Reference the newly exposed fields downstream using the [Variable Reference Syntax](/reference/variable-syntax).
- Review the shapes Glow recognizes in [Data Types & Structures](/build/core-concepts/data-types).