JSON in n8n: Parsing, Transforming and Nesting

Data in n8n is JSON, and most workflow-building problems are not about logic but about the structure not being what you expected.

The data shape

The thing to understand first: data in n8n is an array of items, not a single object.

Each item carries a payload field and, for files, a binary part. A node receives the array and runs once per item.

Half the confusion grows from this:

• The node ran fifty times because fifty items arrived.
• Fifty identical messages went out instead of one.
• An external API received fifty back-to-back requests and rate-limited you.

A practical rule: always check the execution history for how many items reached the node. That is the first thing that explains strange behaviour.

Reaching nested fields

Access follows a path from the item root using dot notation, with array indices where needed.

Three things break expressions most often:

The field is absent. Reaching into a nested value inside a missing field fails the node. Optional data needs a check or safe access - external APIs regularly omit a field rather than sending it empty.

Unusual characters in field names. Dots, hyphens and spaces require bracket access rather than dot notation.

References to nodes by name. Expressions reference other nodes by their title, so renaming a node breaks every expression pointing at it. That is the most galling failure, because it happens while tidying up.

A useful debugging move: dump the whole item in a separate node and look at the real structure. Faster than guessing the path from API documentation that may lag reality.

Structural transformations

Four operations cover nearly everything.

Splitting an array into items. An API response often arrives as one item with an array inside. The split-out node turns that array into separate items that downstream nodes handle one at a time.

Aggregating items into one. The reverse. Needed before sending a single message covering many records, or writing them in one request.

Renaming and selecting fields. Shaping the payload before writing to a destination. Better done explicitly in its own node than smeared across expressions in the target node: that way the outgoing structure is visible.

Merging two streams. Joining data from two sources on a key. The merge mode matters: by position, by key match, or all with all - the last option with a sloppy key produces unexpectedly many items.

The general recommendation: shape the data as early as possible. A workflow where transformation is spread across ten expressions in different nodes cannot be debugged.

Common mistakes

• Expected one item, got an array. Check the execution history.
• Reaching a field that does not exist. Especially after an external API change: the workflow ran for a year and suddenly stopped.
• A number as a string. APIs often return numbers as strings, and comparisons or addition behave unexpectedly. Cast explicitly.
• An empty array versus a missing field. Different cases requiring different checks.
• Encoding and escaping. JSON embedded as a string inside JSON needs its own parse step and shows up more often than you would like.
• Excessive volume. Thousands of items in the execution history slow the interface and bloat the database - see working with APIs.

When you need a code node

Transformation nodes cover the typical cases. Code is for non-trivial structure: recursive traversal, complex grouping, parsing a non-standard format.

A useful boundary: if half the workflow is code, the task has outgrown the visual editor. That fork is covered in alternatives.

Expression basics are in data and expressions. The overview is in the n8n guide.