Struttura dati di n8n: JSON, items e trasformazioni spiegate facile

Se costruisci automazioni per il marketing, capire come viaggiano i dati fa la differenza tra un workflow fragile e uno che scala. In n8n tutto ruota attorno a json n8n: ogni nodo riceve e produce un array di “items”, ciascuno con un wrapper json e, quando serve, una parte binary per i file. Saper leggere, mappare e trasformare questi items significa spedire lead al CRM senza errori, creare copy personalizzati, deduplicare liste e consolidare report. In questa guida pratica entriamo nel vivo della struttura dati di n8n, vedendo come si rappresentano oggetti e array nell’editor, come funzionano le espressioni con $json e $input, e come usare i nodi Split Out, Aggregate e Merge per dividere, raggruppare e combinare stream. Per i casi più tecnici, useremo il Code node per trasformare dati e fare parsing di stringhe JSON, con snippet pronti da copiare. Chiudiamo con best practice di performance e debug, così puoi far crescere i volumi (e i risultati) senza perdere controllo.

📚 Nuovo a n8n? Parti dalla guida completa: cos’è n8n e come funziona.

Che cos’è JSON e come viene visualizzato nell’editor

JSON è il formato di scambio dati più usato nelle API: chiave/valore, tipi semplici (string, number, boolean, null) e strutture complesse (object, array). Nell’editor n8n, ogni nodo mostra l’output in tabella o in struttura ad albero: ciò che vedi è sempre un array di items. A livello visivo, l’editor ti fa navigare facilmente tra i campi e i valori; a livello logico, ogni item è un payload indipendente che fluisce al nodo successivo.

Per i marketer, questo significa due cose:

Ogni record (lead, riga di foglio, evento) è un item: puoi lavorare “per record” e scalare senza cambiare logica.
Le trasformazioni si fanno in modo coerente: un nodo applica la stessa regola a tutti gli items in input.

Esempio di JSON nell’editor per un singolo item:

{

“email”: “maria@example.com”,

“firstName”: “Maria”,

“utm”: { “source”: “ads”, “campaign”: “spring-sale” },

“leadScore”: 87

}

In un workflow reale, quasi sempre l’output di un nodo è un array di items (anche se ne vedi uno solo in test). Questo design rende semplici operazioni come lo split e l’aggregazione di dati in n8n, due pattern che userai spesso per richieste API con risposte “a lista” o per consolidare risultati in un report finale. Capire come l’editor visualizza oggetti (object) e liste (array) ti aiuta a fare mapping dei campi tra nodi con sicurezza, senza confondere singolo item e collezioni.

Keyword utili da ricordare: struttura dati di n8n, array di items nei workflow, mapping dei campi tra nodi.

La struttura dati di n8n: come è fatto un item

In n8n, i dati si muovono sempre come array di items. Ogni item ha:

json: l’oggetto con i tuoi campi business
binary (opzionale): metadata e contenuti file

Esempio completo di item:

{

“json”: {

“email”: “maria@example.com”,

“firstName”: “Maria”,

“utm”: { “source”: “ads”, “campaign”: “spring-sale” },

“leadScore”: 87

“binary”: {

“attachment”: {

“fileName”: “brochure.pdf”,

“mimeType”: “application/pdf”,

“data”: “…”

}

Dettagli importanti:

items e campo json in n8n: il wrapper json è obbligatorio. Dalla v0.166.0, se dimentichi “json” n8n prova ad aggiungerlo automaticamente, ma è buona pratica rispettare la struttura.
Differenza tra singolo item e più items: molti nodi (es. HTTP Request) possono restituire 1 item con dentro un array; altri producono già più items. Sapere cosa hai in mano evita errori di path.
Gestione dati binari in n8n: se lavori con allegati (PDF dell’offerta, immagini prodotto), il binary vive accanto al json; molti nodi espongono opzioni per includere/propagare i binari.

Per marketing, un pattern efficace è definire presto i campi chiave (nome, email, campaign, segment, score) e mantenerli coerenti lungo il flusso. Questo rende naturale la validazione di oggetti JSON e la creazione di copy personalizzati per email/Slack. Se arrivano risposte API complesse (nested array), userai i nodi di trasformazione per riallinearle alla struttura attesa.

Long-tail consigliate: struttura dati di n8n, items e campo json in n8n.

Espressioni e mapping: $json, $input e reference tra nodi

Le espressioni trasformano campi statici in dinamici. Alcune forme utili:

Valori correnti: {{ $json.email }}
Annidati: {{ $json.utm.campaign }}
Da un nodo precedente: {{ $node[“HTTP Request”].json.results[0].name }}
Fallback: {{ $json.company || “N/A” }}
Composizione: {{ $json.firstName + ” ” + $json.lastName }}
Tipi e calcoli: {{ Number($json.total) * 1.22 }}

Con espressioni con $json e $input puoi anche lavorare sui dataset in nodi avanzati:

$input.first(): primo item in input
$input.all(): tutti gli items in input (utile nel Code node per aggregazioni personalizzate)

Esempi rapidi di mapping dei campi tra nodi:

Oggetto email dinamico (Gmail > Subject):

Nuova richiesta da {{ $json.firstName }} per la campagna {{ $json.utm.campaign }}

Link a dati di un HTTP Request precedente:

Best practice:

Mantieni i nomi campo coerenti (Set node per creare oggetti “puliti” all’ingresso).
Evita path errati su array annidati (verifica se stai leggendo l’elemento [0] o una lista intera).
Attento ai tipi inattesi: se un’API restituisce numeri come stringhe, convertili dove serve.

Per i marketer è la base della personalizzazione: unisci i dati di origine (form, CRM, analytics) e costruisci messaggi/segmentazioni con poche espressioni. Così automatizzi nurturing, scoring e notifiche restando allineato al contesto.

Long-tail consigliate: espressioni con $json e $input, reference a valori annidati.

Trasformazioni no-code: Split Out e Aggregate

n8n fornisce due nodi core per trattare liste senza scrivere codice:

Split Out: separa una lista in più items
Aggregate: raggruppa più items in un singolo oggetto/lista

Split Out node (separare un array in items)

Field to Split Out: il campo che contiene la lista (es. results)
Include: scegli se includere “No Other Fields”, “All Other Fields” o “Selected Other Fields”
Opzioni utili: Disable Dot Notation, Destination Field Name, Include Binary

Scenario tipico: un’API ritorna { results: […] } come unico item.

Configurazione:

Field to Split Out: results
Include: No Other Fields

Risultato: avrai un item per ogni elemento di results. Perfetto per iterare su lead, prodotti, eventi.

Aggregate node (raggruppare items)

Modalità principali:

Individual Fields: raccogli singoli campi in liste
Input Field Name, Rename Field (toggle), Output Field Name
Opzioni: Disable Dot Notation, Merge Lists, Include Binaries, Keep Missing And Null Values
All Item Data: metti tutti i dati in un campo lista
Put Output in Field (es. data_object)
Include: All fields, Specified Fields, All Fields Except

Caso d’uso marketing: consolidare 100 risultati in un unico item per inviare un report ai colleghi o alla BI.

Configurazione All Item Data:

Put Output in Field: data_object
Include: All fields

Risultato: un item con json.data_object contenente la lista completa.

Questo approccio copre gran parte delle esigenze comuni: split e aggregazione di dati in n8n senza toccare codice, riducendo errori e tempi di sviluppo.

Long-tail consigliate: split e aggregazione di dati in n8n, Aggregate/Split Out.

Trasformazioni con codice: Code node e parsing di stringhe JSON

Quando le regole superano i limiti del no-code, entra in gioco il Code node per trasformare dati. Puoi usare:

Run Once for Each Item: modifica item per item
Run Once for All Items: opera su tutto il batch in una volta (aggregazioni, pivot, enrichment)

Esempi pratici:

Creare un dataset da zero

return [

{ json: { name: ‘Alice’, email: ‘alice@example.com’ } },

{ json: { name: ‘Bob’, email: ‘bob@example.com’ } }

];

Arricchire ogni item

let items = $input.all();

for (const item of items) {

item.json.fullName = ${item.json.firstName} ${item.json.lastName};

item.json.segment = item.json.leadScore >= 80 ? ‘VIP’ : ‘Standard’;

}

return items;

Splittare un array presente nel primo item (equivalente a Split Out)

return $input.first().json.results.map(r => ({ json: r }));

Aggregare tutti gli items in un unico campo

return [

{

json: {

data_object: $input.all().map(i => i.json)

}

];

Parsing di stringhe JSON in n8n (API che rispondono con JSON “in stringa”)

In un’espressione: {{ JSON.parse($json.payload) }}
Nel Code node con gestione errori:

const first = $input.first();

let parsed;

try {

parsed = JSON.parse(first.json.payload);

} catch (e) {

parsed = { parseError: String(e), raw: first.json.payload };

}

return [{ json: parsed }];

Questa tecnica risolve un pain point diffuso (mancanza di un “JSON Parser” dedicato) e consente validazione, fallback e logging. Aggiungi check su chiavi obbligatorie e tipi (string, number, boolean, null, array, object) per prevenire rotture downstream.

Long-tail consigliate: Code node per trasformare dati, parsing di stringhe JSON in n8n.

Combinare stream: Merge node e combinazione di items

Il Merge node combina flussi multipli con diverse modalità. Parametri chiave:

Mode: Append

Mantiene tutti i dati di ogni input in sequenza
Number of Inputs: scegli quanti ingressi unire

Uso tipico: concatenare liste da fonti diverse.

Mode: Combine

Combine By: tre strategie

Matching Fields

Fields to Match: campi su cui confrontare (es. language)
Output Type: Keep Matches (inner join), Keep Non-Matches, Keep Everything (outer), Enrich Input 1 (left), Enrich Input 2 (right)

Position

Combina per indice (item 0 con item 0, ecc.)
Opzione: Include Any Unpaired Items per mantenere gli items “senza coppia”

All Possible Combinations

Prodotto cartesiano di tutte le combinazioni

Options (Combine)

Clash Handling: priorità tra input in caso di stesso nome campo; Deep Merge vs Shallow Merge
Fuzzy Compare: “3” e 3 considerati uguali se attivo
Disable Dot Notation: disabilita l’accesso tipo parent.child
Multiple Matches: Include All Matches oppure Include First Match Only

Altre modalità:

SQL Query: scrivi query (AlaSQL) tipo SELECT … JOIN per un controllo totale
Choose Branch: scegli quale input mantenere (Input 1 Data, Input 2 Data, Single, Empty Item)

Esempio “saluta utenti nella loro lingua”:

Input 1 (utenti): [{ name: ‘Stefan’, language: ‘de’ }, { name: ‘Jim’, language: ‘en’ }]
Input 2 (greeting): [{ greeting: ‘Hallo’, language: ‘de’ }, { greeting: ‘Hello’, language: ‘en’ }]

Configurazione:

Mode: Combine
Combine By: Matching Fields
Fields to Match: language (per entrambi gli input)
Output Type: Keep Matches

Risultato: ogni utente ha il greeting corretto.

Insight pratico: per dataset irregolari, testa “Position” con Include Any Unpaired Items, oppure passa a “Matching Fields” con Keep Everything per non perdere righe utili.

Long-tail consigliate: Merge node e combinazione di items, mapping dei campi tra nodi.

Debug, validazione e performance su grandi dataset

Errori tipici da evitare:

JSON come stringa non parsata: risolvi con JSON.parse in espressione o Code node
Path errati su array annidati: verifica se accedi a [0] o alla lista intera
Tipi inattesi (string vs number): normalizza prima dei confronti/ordinamenti
Campi mancanti/null: definisci default o scarta in modo esplicito

Tecniche di debug nell’editor e con il Code node:

Test incrementale: Manual Trigger → 1 nodo → verifica struttura → aggiungi passi
Data pinning: fissa l’output di un nodo per test ripetibili senza chiamare API
Check mirati: aggiungi un Edit Fields (Set) o Code per validare chiavi obbligatorie (email, campaign) e normalizzare valori null/undefined
Logging: costruisci un item “log” aggregato a fine flusso con Aggregate (All Item Data) per ispezioni rapide

Best practice per performance con molti items:

Filtri a monte: usa Limit/Filter prima di chiamate costose
Loop Over Items (Split in Batches): processa in batch (es. batchSize 50) per rispettare rate limit e memoria
Trasformazioni incrementali: split → process → aggregate solo se necessario
Attenzione ai nodi “costosi”: riduci chiamate API duplicate usando il pin in sviluppo e caching logico dove possibile

Snippet di validazione in Code node (chiavi obbligatorie):

let items = $input.all();

const required = [’email’, ‘utm’, ‘leadScore’];

items = items.filter(i => required.every(k => i.json[k] !== undefined && i.json[k] !== null));

return items;

Questo approccio alza la qualità del dataset e riduce gli errori a valle (es. invii falliti verso CRM o tool email).

Long-tail consigliate: best practice per performance con molti items, validazione di oggetti JSON.

Quick Takeaways

La struttura dati di n8n è un array di items con wrapper json: progetta flussi pensando “per item”.
Usa espressioni con $json e $input per mapping robusti e copy dinamici senza codice.
Split Out e Aggregate risolvono l’80% delle trasformazioni su liste senza scrivere JS.
Merge combina stream in modi diversi (Matching Fields, Position, All Possible Combinations) con opzioni utili come Clash Handling e Fuzzy Compare.
Per parsing di stringhe JSON in n8n usa JSON.parse in espressione o nel Code node con try/catch.
Con dataset grandi, filtra a monte e usa Loop Over Items (Split in Batches) per stabilità e rispetto dei limiti API.

Conclusione

Padroneggiare json n8n significa saper leggere e modellare i dati alla base delle tue automazioni. Abbiamo visto come l’editor rappresenta oggetti e array, come funziona il wrapper degli items e come impostare mapping affidabili con espressioni. Con Split Out e Aggregate trasformi liste in pochi clic, mentre il Code node ti dà la flessibilità per parsing e regole complesse. Il Merge node ti consente di ricomporre stream in modo preciso, con modalità che coprono sia casi “one-to-one” che “many-to-many”. Infine, un approccio di debug e performance orientato a test incrementali, validazione e batch ti assicura flussi stabili anche a volumi elevati.

Se vuoi accelerare la produttività di marketing, parti da un caso reale (raccolta lead, enrichment, segmentazione) e costruisci il flusso così: normalizza con Set, splitta con Split Out, arricchisci, fai merge dove serve e consolida un report con Aggregate. Testa con pin, valida le chiavi critiche e passa a batch in produzione. Il risultato sarà un’automazione più solida, veloce da mantenere e pronta a scalare con le tue campagne.

FAQ

Che cosa sono gli “items” e il campo json in n8n?

Ogni nodo scambia un array di items; ciascun item ha un wrapper json con i dati business e, opzionalmente, binary per i file. È la base della struttura dati di n8n.

Come faccio il mapping tra nodi con espressioni?

Usa espressioni con $json e $input: ad esempio {{ $json.email }} o {{ $node[“HTTP Request”].json.results[0].name }}. Così referenzi valori annidati e output di nodi precedenti.

Come divido una lista in più items senza codice?

Con lo Split Out node. Imposta Field to Split Out (es. results) e scegli Include (No/All/Selected Other Fields). Otterrai un item per elemento della lista.

Come raggruppo più items in un unico oggetto/lista?

Con l’Aggregate node. In “All Item Data”, imposta Put Output in Field (es. data_object) e l’opzione Include. In “Individual Fields” puoi aggregare campi specifici con opzioni come Merge Lists.

Come parse un JSON che arriva come stringa?

In un’espressione: {{ JSON.parse($json.payload) }}. Oppure nel Code node con try/catch per gestire errori. È il workaround più pratico al parsing di stringhe JSON in n8n.

Hai trovato utile questa guida? Dimmi quale passaggio della struttura dati di n8n ti ha chiarito di più le idee e condividila con il tuo team: quale workflow basato su JSON vuoi ottimizzare per primo?