n8n nodes receive items, apply an operation, and emit items along connections. Reliable workflows make the data contract at each boundary visible. A green node does not prove the business state is correct.
Model Items Explicitly
Use a canonical envelope:
{
"event_id": "evt-sample-01",
"event_type": "lead.submitted",
"occurred_at": "2026-07-19T10:00:00Z",
"tenant_ref": "sample-shop",
"payload": { "city": "Karachi", "service": "catalog setup" },
"schema_version": "1"
}
At each node record expected fields, output fields, cardinality, empty-input behavior, and error behavior. Avoid mutating a broad untyped object throughout the workflow. Select and rename the fields each stage owns.
Understand Branching and Merging
An IF/Switch branch creates separate paths. A Merge node’s result depends on mode and item linking. Test zero, one, and many items on every branch. Do not assume branch order or pair records by position if an ID join is required.
For batch operations, preserve event_id or business reference. If one input produces several outputs, add a stable child key. If several inputs aggregate, record the source IDs.
Worked Example
A sample order list contains three items. The workflow validates each, branches supported and unsupported cities, and produces two accepted drafts plus one review case. A merge by stable order_ref combines approved catalog data; it does not join “first with first.”
The output includes counts and source references. Empty input yields an explicit NO_ITEMS result rather than silently succeeding and triggering a downstream message.
Save this execution as a regression fixture so later node or n8n upgrades must preserve the same accepted, review, and empty-item behavior.
Failure Cases to Diagnose
- Position-based merge after filtering: join by stable ID.
- Node drops identifiers: carry trace and business refs.
- Empty branch treated as success: define zero-item behavior.
- Large binary copied through every node: store/reference appropriately.
- Expression points to a different branch item: inspect linking and execution data.
- Schema changes silently: version and validate boundaries.
🇵🇰 Pakistan Angle
Normalize Pakistani phone numbers only after user confirmation and keep the original authorized source. Do not use phone, city, name, or language as a proxy for sensitive traits or customer value.
For orders, preserve exact PKR fields and source. A formatted PKR 2,490 string is for display; arithmetic should use a documented exact representation. Never merge a payment event to an order by customer name.
Hands-On Exercise
- Define one canonical event envelope.
- Annotate each node’s input/output/cardinality.
- Test zero/one/many items.
- branch and merge using stable IDs.
- export three execution fixtures.
Completion Rubric
- Every boundary has a data contract.
- IDs survive transformations.
- Branch and merge semantics are tested.
- Empty and multiple-item cases are explicit.
- Schema versions are visible.
- Financial and identity joins use authoritative references.
Sources
Key takeaway: design every connection as a typed item boundary with stable identity, explicit cardinality, and tested zero/many behavior.