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.
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:
{{ $node[“HTTP Request”].json.data.url }}
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:
1) Creare un dataset da zero
return [
{ json: { name: ‘Alice’, email: ‘alice@example.com’ } },
{ json: { name: ‘Bob’, email: ‘bob@example.com’ } }
];
2) 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;
3) Splittare un array presente nel primo item (equivalente a Split Out)
return $input.first().json.results.map(r => ({ json: r }));
4) 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
1) 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)
2) Position - Combina per indice (item 0 con item 0, ecc.)
- Opzione: Include Any Unpaired Items per mantenere gli items “senza coppia”
3) 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
1) 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.
2) 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.
3) 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.
4) 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.
5) 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?
Scopri la consulenza →