---
title: "JSON Formatter"
icon: "braces"
---

The **JSON Formatter** step gives you exact control over your JSON payloads in Agent Studio. Build them visually or hand‑craft them in a raw editor, then pass the result to downstream steps.

---

## TL;DR

- **Two modes:** Visual Builder and Raw JSON Editor.
- **Use cases:** Shape final payloads, normalize LLM output, or build arrays for Loops.
- **Where:** **Steps → Data Formatter → JSON Formatter**.
- **Output:** A valid JSON value (object/array/primitive) resolved at runtime.

---

## When to use the JSON Formatter

Use the step when you need to:

- **Guarantee a specific schema** for downstream systems (APIs, db writes, exports).
- **Normalize/clean LLM output** into predictable keys and types.
- **Assemble arrays** of items for a **Loop** (e.g., iterate over `items[]`).
- **Rename keys or remap fields** without touching previous steps.

If you only need to pass a single variable through, you can skip this step; but for anything schema‑related, the JSON Formatter is the safest place to lock it in.

---

## Modes

### Visual Builder (no‑code)

An interactive canvas for assembling JSON with **key/value pairs** and nested structures. Type or paste variable tokens using the `<stepResult value="..."/>` syntax (see below).

**Highlights**

- Add **objects** and **arrays** with one click.
- Insert variables without syntax mistakes.
- Inline validation \+ live **Preview** of the resulting JSON.

**Great for:** quick mapping, small–medium payloads, avoiding syntax errors.

---

### Raw JSON Editor (power users)

Write or paste **any valid JSON**. The editor validates the syntax and shows the structured preview.

**Highlights**

- Full control over nested objects/arrays.
- Easy copy/paste from specs or other tools.
- Supports the same token syntax (`<stepResult value="..."/>`).

> **Note**: The editor validates **JSON** (not JavaScript). Use double quotes for keys/strings and no trailing commas.

---

## Variable tokens (syntax)

Variables are inserted as **self‑closing tokens**. For example, referencing a previous step result named **AI Model** inserts:

```text
<stepResult value="AI Model"/>
```

- Type tokens manually using the syntax below. Copy/paste to avoid typos.
- In **Visual Builder**, type or paste tokens into the value field. The builder handles escaping and quoting for you.
- In **Raw JSON Editor**, place tokens **inside JSON strings** so the JSON remains valid.

> At runtime, tokens resolve to their actual values **before** the JSON is sent to downstream steps.

---

## Quick start

1. In **Agent Studio**, add **JSON Formatter** from **Data Formatter**.
2. Choose **Visual Builder** or **Raw JSON Editor**.
3. Type the token syntax (e.g., `<stepResult value="AI Model"/>`).
4. (Optional) Add arrays/objects and nest as needed.
5. Connect the JSON Formatter’s output to an **Output** or a **Loop** step.

---

## Validation & preview

- The editor validates the JSON structure on the fly.
- The **Preview** panel reflects the structure with tokens in place; during execution, tokens resolve to values.
- Any **errors** appear inline; fix and continue without losing your work.

---

## Best practices

- **Freeze your schema** before integrating with external systems.
- **Name keys for consumers**, not creators—keep a consistent case (`snake_case` or `camelCase`).
- **Keep arrays homogenous** (same keys/types per item) to make Loop logic simple.
- Use the token syntax consistently; copy/paste to avoid typos.

---

## Troubleshooting

**“Invalid JSON” in Raw Editor**

- Tokens must be inside **quoted** strings (e.g., `"<stepResult value=\"AI Model\"/>"`).
- Check for trailing commas, single quotes, or missing quotes on keys.

**Token didn’t resolve**

- The referenced step name must match exactly (e.g., `AI Model`). Re-type the token exactly or copy/paste from the source step name to be sure.

**Loop doesn’t iterate**

- Confirm the JSON Formatter outputs a **top‑level array** (e.g., `[ {...}, {...} ]`).

**Unexpected nulls**

- The source variable may be missing at runtime. Provide a default value earlier or change the mapping.

---