> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Formatter

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 theme={null}
<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.

***