Understanding Data in n8n | JSON, Lists & Items in n8n Explained

Ever struggled with data not flowing correctly in your n8n workflows? Maybe data is missing, corrupted, or not in the format you expected. In this lesson, you’ll learn how data is structured and flows in n8n, focusing on JSON, lists (arrays), and items. Understanding these fundamentals will empower you to manipulate, transform, and troubleshoot data effectively in your automations.

If you're new to n8n, consider starting with Build Your First n8n Workflow to get a practical introduction to how data flows through nodes.

Understanding JSON: The Backbone of Data in n8n

What is JSON?

JSON stands for JavaScript Object Notation. It is a lightweight, text-based format used to represent structured data as key-value pairs. JSON is widely used because it is:

• Human-readable and easy to understand
• Flexible enough to represent complex data structures
• Universally supported across programming languages and platforms

Why Use JSON Instead of Tables?

Imagine placing an order on an e-commerce platform like Amazon. Your order contains details such as:

• Order number
• Customer name and contact info
• Shipping address
• Product details (which vary depending on the product type)
• Payment information

Storing all this data in a tabular format (rows and columns) is rigid because different products have different attributes. For example:

Here, many columns would be empty or irrelevant depending on the product, making the table inefficient.

JSON solves this by allowing nested objects and arrays, providing flexibility while maintaining structure.

JSON Example: Single Product Order

{
  "orderNumber": "ORD0001",
  "customerName": "John Doe",
  "address": "123 Main St, City, Country",
  "order": {
    "product": {
      "name": "Smartphone",
      "type": "Electronic",
      "screenSize": "6.1 inches",
      "memory": "128GB",
      "price": 699,
      "quantity": 1,
      "status": "shipped"
    }
  }
}

This JSON object contains nested data describing a smartphone order. Notice the flexibility — the product object can hold any number of properties specific to the product type.

JSON Example: Different Product Type

{
  "orderNumber": "ORD0002",
  "customerName": "John Doe",
  "address": "123 Main St, City, Country",
  "order": {
    "product": {
      "name": "Avengers T-shirt",
      "color": "Red",
      "material": "Cotton",
      "size": "Medium",
      "price": 19,
      "quantity": 2,
      "status": "delivered"
    }
  }
}

Here, the product is a t-shirt, with different attributes like color and material. JSON's flexibility allows storing both smartphone and t-shirt orders in the same structured format without wasting space or complicating queries.

Handling Multiple Products: Lists (Arrays) in JSON

What is a List or Array?

A list (or array) is an ordered collection of items enclosed in square brackets []. Each item can be an object, a string, a number, etc. Lists allow you to store multiple values under the same key.

Example: Single Order with Multiple Products

{
  "orderNumber": "ORD0003",
  "customerName": "John Doe",
  "address": "123 Main St, City, Country",
  "order": {
    "products": [
      {
        "name": "iPhone",
        "type": "Smartphone",
        "screenSize": "6.1 inches",
        "storage": "128GB",
        "price": 699,
        "quantity": 1
      },
      {
        "name": "Avengers T-shirt",
        "color": "Red",
        "material": "Cotton",
        "size": "Medium",
        "price": 19,
        "quantity": 2
      }
    ]
  }
}

In this example, the key products holds a list of two product objects, each with their own attributes. The list allows you to group multiple items under a single order flexibly.

If you want to transform or add new fields to such data, the Set Node in n8n is a great tool to help you manipulate JSON objects and arrays efficiently.

Accessing Data in JSON Using Dot Notation and Indexing

Basic Access with Dot Notation

JSON data is accessed by chaining keys with dots:

order.customerName // "John Doe"
order.orderNumber  // "ORD0001"

Accessing Items in Lists Using Indexes

Lists are zero-indexed arrays. To access the first item, you use [0], the second item [1], and so on.

For example, if you have a list of orders called orders:

orders[0].orderNumber // Returns the order number of the first order
orders[1].customerName // Returns the customer name of the second order

Accessing Nested Properties

Combine dot notation and array indexing to drill down into nested JSON:

orders[0].order.product.name // "Smartphone"
orders[1].order.product.price // 19

Accessing Multiple Products in a Single Order

Using the previous order with multiple products:

order.order.products[0].name // "iPhone"
order.order.products[1].price // 19

How n8n Handles Data: Items and Lists

What is an Item in n8n?

In n8n, items represent individual data units that flow through nodes. Each item corresponds to one JSON object.

When a node receives multiple items (a list), it processes each item individually but in the same execution.

How Does Data Flow Between Nodes?

• Input data to a node is an array of items.
• Each node processes every item one by one, applying the node's logic or transformation.
• The output is usually the same number of items, but with modified or enriched data.

For example, if a trigger node outputs 5 orders (items), the next node will receive all 5 items and process them separately.

Understanding this concept is crucial when designing workflows with conditional paths or parallel processing. For more on this, check out How Branching Works in n8n.

Why Is This Important?

Understanding that nodes operate on lists of items helps you:

• Build workflows that handle multiple records efficiently
• Use loops and conditional logic correctly
• Avoid common pitfalls where data seems missing or duplicated

Practical Example: Accessing and Manipulating JSON Data in n8n

Step 1: Trigger Node Producing Multiple Items

Imagine a trigger node HTTP Request or Webhook that receives multiple orders in JSON format:

[
  {
    "orderNumber": "ORD0001",
    "customerName": "John Doe",
    "order": {
      "product": {
        "name": "Smartphone",
        "price": 699
      }
    }
  },
  {
    "orderNumber": "ORD0002",
    "customerName": "Jane Smith",
    "order": {
      "product": {
        "name": "T-shirt",
        "price": 19
      }
    }
  }
]

This is an array of two items.

Step 2: Access Data Using n8n Expressions

In any node that supports expressions (like Set, Function, or IF), you can access data from the incoming items using the following syntax:

{{$json["orderNumber"]}}          // Access order number of current item
{{$json["order"]["product"]["name"]}}  // Access product name of current item

For more details on expressions and how to use them effectively, refer to the n8n Expressions Documentation{:target="_blank"}.

Step 3: Loop Through Multiple Products in a Single Order

If an item contains a list of products, you can use a SplitInBatches node or a Function node to iterate over the products array.

Example expression to access the first product's price:

{{$json["order"]["products"][0]["price"]}}

To try out these concepts hands-on, the n8n Try It Out Guide{:target="_blank"} is a helpful resource.

Common Mistakes and Troubleshooting

• Confusing Arrays and Objects: Remember, arrays use square brackets [] and objects use curly braces {}. Accessing them incorrectly will cause errors.

• Wrong Indexing: Arrays start at index 0. Trying to access an index out of bounds will return undefined.

• Assuming Same Structure for All Items: Not all items have identical properties. Use checks or conditional logic before accessing nested keys.

• Forgetting to Use Expressions in Nodes: When referencing JSON data within n8n nodes, always wrap your access in {{$json["key"]}} or {{$json.key}} expressions.

• Ignoring Data Shape: Use the Execute Node preview to inspect the exact structure of your data between nodes. This helps avoid errors.

Additional Resources

• n8n Expressions Documentation
• Working with Data in n8n

Quick Reference Cheat Sheet

By mastering JSON structures, lists, and how n8n processes items, you will build more reliable and scalable automation workflows. As shown in the video above, understanding these data concepts is foundational to troubleshooting and optimizing your n8n automations effectively.