The JSON Node reads a JSON or JSONL file and yields each record to the loop body one at a time — and can also write a list of objects out as a JSON array or line-delimited JSONL file.
Overview
The JSON Node is an iterator node that steps through a JSON or JSONL (one-object-per-line) file record by record, delivering each to the steps inside the loop body rather than loading the entire file upfront. It also supports a write operation so you can produce or append to a JSON or JSONL file as part of the same automation. Use it to walk API exports, database dumps, or data pipeline outputs stored as JSON — transforming or routing each record as it flows through.
JSONL (JSON Lines) format is particularly well-suited to streaming because each line is a self-contained object, making it straightforward to read or write incrementally. If you control the format of your input files, prefer JSONL for large datasets over a single large JSON array.
Reading JSON Files
The read operation iterates a JSON or JSONL file and yields records — one at a time or in batches — to everything inside the loop body. Each pass through the loop receives the current record along with metadata about its position in the file.
Inputs
Field | Description |
|---|---|
File | The JSON or JSONL file to iterate. Files are read as UTF-8 by default. |
Starting Record | The record number to begin reading from. Counted from 1 — record 1 is the first record in the file. Use this to resume from a checkpoint or skip a known number of already-processed records. |
Batch Size | Optional. The number of records to hand to the loop body per iteration. Defaults to approximately 100. Use batching to reduce per-record overhead on large files — processing 100 records per loop pass is far more efficient than 10,000 individual passes. |
Loop Outputs
The following values are available inside the loop body on each pass:
Output | Description |
|---|---|
Item | The current record (or batch of records, when batch size is set) from the file. |
Index | The zero-based position of the current item within the iteration. |
Is First | True on the first iteration pass. Use this to run setup logic — opening a target file, initialising a counter — without adding a conditional branch to every pass. |
Is Last | True on the final iteration pass. Use this to flush a buffer or close a resource after the last record has been processed. |
Batch mode: When Batch Size is set, Item contains a list of records rather than a single record. Your loop body steps should be written to handle a list. For most high-volume files, a batch size around 100 strikes a good balance between overhead and memory use — tune it based on the complexity of your loop body.
Writing JSON Files
The write operation takes a list and writes it to a file as either a JSON array (nicely indented) or as JSONL (one object per line). Use it at the end of a processing loop to materialise results, or as a standalone step to produce a structured output file.
Inputs
Field | Description |
|---|---|
Data | The list of objects to write. |
Output Format | JSON writes a nicely indented array. JSONL writes one object per line, which is better suited to streaming and large files. |
Target File | The file path to write to. |
Append | When enabled, adds to an existing file rather than replacing it. The target file must be well-formed — appending to a corrupt or hand-edited file can fail. |
Append mode gotcha: Append edits the existing file's structure in place. Use it only when you are deliberately accumulating records across runs or loop passes into a single file. For a fresh, predictable output each time, write without append.
Notes
Keep the following in mind when using the JSON Node.
Prefer JSONL format for large datasets — its line-delimited structure makes streaming and partial reads more reliable than a single large JSON array.
Starting Record is counted from 1. Record 1 is the first record in the file.
Files are read as UTF-8 by default.
Use batch mode for high-volume files to trade per-record overhead for per-batch overhead. Tune the batch size based on the complexity of your loop body steps.
Use the Is First and Is Last flags to run setup or teardown logic once without adding conditional branches to every loop pass.
When writing with Append enabled, ensure the target file is always well-formed before the automation runs — a corrupted file will cause the append operation to fail.
For a fresh, predictable output file on each run, write without append mode.