Data Flow in n8n: Understanding Items and JSON

Hello! Welcome to your fifth lesson.

In our previous session, we established the fundamental architecture of an n8n workflow: a single trigger node that defines when a workflow starts, followed by one or more action nodes that define what it does. We briefly mentioned that data flows from the trigger through this chain of actions.

Today, we're going to dive deep into that "flow." We'll dissect the precise format and structure of data as it moves through an n8n workflow. This is arguably the most critical concept for moving beyond simple automations. For a developer, understanding an application's core data model is paramount, and in n8n, that model is the item-based data structure.

By the end of this lesson, you will be able to describe n8n's item-based data structure and explain how this JSON data flows between nodes. Mastering this will be essential for handling API responses, transforming data, and building the complex, multi-step automations you're aiming for.

1. The Core Data Structure: An Array of Items

In n8n, data doesn't just flow as a single file or a blob of text. It has a very specific, consistent structure: an array of JSON objects, where each object is called an "item."

Every piece of data that passes from one node to the next is packaged in this format. To get a clear visual and conceptual introduction, let's start with a short video from the n8n team.

As the video explained, the hierarchy is simple but strict:

1. The Top Level: An array, which n8n calls items.
2. Inside the Array: One or more objects, each representing a single item.
3. Inside Each Item: A key named json whose value is another object containing your actual data (e.g., customer name, order ID, email address).

The official n8n documentation provides a clear textual definition of this structure. Since you're familiar with arrays and objects from your software development background, this should be a quick and reinforcing read.

Here is the essential diagram from that documentation which summarizes the entire concept:

For file-based workflows, you might also see a binary key alongside the json key, but for now, we'll focus on the ubiquitous json data.

2. The Flow: How Items Move Between Nodes

Now that we know what the data looks like, let's understand how it moves. The process is as follows:

1. A node (e.g., Node A) finishes its execution.
2. It outputs a complete array of items.
3. The next connected node (Node B) receives that entire array as its input.
4. Node B then performs its operation.

Crucially, most nodes will automatically perform their action on every single item they receive. This is a powerful feature called implicit looping. If a node receives 10 items, it will run its logic 10 times, once for each item, without you needing to build an explicit for loop.

This video demonstrates the concept perfectly using a Google Sheets example.

To give you the more architectural view that might resonate with your background, this process can be formally described. Data flows through the workflow as a complete array of items at each step.

3. Why This Structure is Crucial: A Common Pitfall

This item-based structure is the key to n8n's power, but it's also a common source of confusion for newcomers. The problem arises when an external service or API gives you data that looks like a list but isn't structured as n8n items.

Common Scenario: You make an HTTP request to an API to get a list of users. The API returns a single JSON object that contains a key, maybe called results, whose value is an array of user objects.

{
  "count": 2,
  "results": [
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob", "email": "bob@example.com" }
  ]
}

To n8n, the above data is ONE item. The json property of that single item contains a key called results which happens to be an array. If you pass this single item to a "Send Email" node, it will only run once and won't know how to handle the array inside.

To make this work, you need to transform this single item into TWO items, one for Alice and one for Bob. This is a fundamental pattern in n8n: restructuring incoming data to match the item-based model.

The following videos demonstrate this exact problem and the solution.

{
    "data": [
        { "id": "prod_1", "name": "Laptop", "stock": 42 },
        { "id": "prod_2", "name": "Mouse", "stock": 137 },
        { "id": "prod_3", "name": "Keyboard", "stock": 78 }
    ],
    "retrieved_at": "2023-10-27T10:00:00Z"
}

Conclusion

Understanding n8n's data structure is like learning the fundamental data types of a new programming language. It governs everything. Once you internalize this model, debugging becomes exponentially easier, and you'll intuitively know how to handle data from any source.

Key Takeaways:

• All data in n8n flows as an array of items.
• Each item is a standard object that must contain a json property holding the actual data.
• Nodes typically operate on every item they receive, a concept called implicit looping.
• A common and critical task is transforming data from external sources (which often comes as a single object with an array inside) into n8n's multi-item structure.

In our next lesson, we'll get even more practical. We will learn how to inspect node input and output data using the execution view. This will allow you to see the exact item structure at every step of your workflow, which is the primary skill used for debugging.