n8n's data structure: items
In n8n, all data passed between nodes is an array of objects. Each element of that array is an item, and each item can carry two keys:
json— ordinary data (strings, numbers, nested objects)binary— file data (images, PDFs, archives)
Internalising this structure once resolves most of the problems people hit in n8n. Practically, picture an item as one row in a table: five rows into a node means the node runs five times.
[
{
"json": {
"apple": "beets",
"carrot": { "dill": 1 }
},
"binary": {
"apple-picture": {
"data": "....", // base64, məcburi / required
"mimeType": "image/png", // tövsiyə olunur / recommended
"fileExtension": "png",
"fileName": "example.png"
}
}
}
]The item structure as documented officially. `binary` is only present when there is a file.
One item = one run. The practical consequences of that rule:
- Ten items into an HTTP Request node means ten requests
- Ten items into a Gmail node means ten emails
- A node's output item count can differ from its input: Filter reduces, Split Out increases, Aggregate collapses everything into one item
Nested data. APIs often return data nested. n8n's table view shows nested fields in bold, signalling that there is more structure inside. To use such fields you either write the full path, or turn the array into separate items with the Split Out node.
The Code node (and the older Function node) is one exception: since n8n 0.166.0, if you forget the json key or the array wrapper there, n8n adds them for you. That leniency applies only to those nodes — when you build your own node you must return the json key yourself.
📚 Sources and documentation
- Understand n8n's data structureofficialdocs.n8n.io
The official source of the JSON structure above.
- Work with data — overviewofficialdocs.n8n.io
- Split Out nodeofficialdocs.n8n.io
For turning a nested array into separate items.