n8nのitemsとJSONを理解する｜node間を流れるデータ構造の基本

n8nのWorkflowは、nodeを線でつないだ図として表示されます。しかし、実際にnode間を移動しているのは線ではなくデータです。

前のnodeのOUTPUT
→ connection
→ 次のnodeのINPUT

このデータの基本単位がitemです。itemの内容は主にJSON形式で表され、1件の場合も複数件の場合も、n8nはitemsの集まりとして処理します。

itemsとJSONを理解すると、Expression、条件分岐、API連携、データ変換で「どの値を参照しているのか」が見えるようになります。

今日の到達点

この記事を読み終えると、次の内容を説明できるようになります。

• item、field、object、arrayの違い
• 1 itemと複数itemsのデータ構造
• nodeのOUTPUTが次のnodeのINPUTになる仕組み
• Table表示とJSON表示の対応関係
• $jsonが現在処理中のitemを参照する意味
• 通常のJSONデータとbinary dataの違い

n8nのデータはitemsの配列として流れる

n8n公式ドキュメントでは、node間で渡されるデータはobjectのarrayとして説明されています。

基本形は次のとおりです。

[
  {
    "json": {
      "name": "Hydraulic pump",
      "pressure_mpa": 10
    }
  }
]

外側の[]は、複数のitemをまとめるarrayです。

その内側にある一つのobjectが1 itemに対応します。通常の構造化データは、各itemのjsonプロパティ内へ格納されます。

itemsのarray
└─ item
   └─ json
      ├─ name
      └─ pressure_mpa

画面のOUTPUTでは、表示方法によってjsonの内側だけが見える場合があります。UI上の見え方と、node間データの基本構造を混同しないことが重要です。

itemとは何か

itemは、n8nが処理する1レコード分のデータです。

たとえば、3種類の機器を扱う場合、それぞれを1 itemとして表現できます。

[
  {
    "json": {
      "name": "Pump A",
      "pressure_mpa": 10
    }
  },
  {
    "json": {
      "name": "Valve B",
      "pressure_mpa": 14
    }
  },
  {
    "json": {
      "name": "Cylinder C",
      "pressure_mpa": 7
    }
  }
]

このデータには3 itemsあります。

n8nの多くのnodeは、入力された複数itemsを自動的に1件ずつ処理します。3 itemsを受け取ったnodeが各itemへ同じ処理を行えば、通常は3 items分の結果が出力されます。

3 input items
→ nodeが各itemを処理
→ 3 output items

1 itemだけを処理しているつもりで設計すると、複数itemsが入力されたときにメール送信やデータ登録が件数分実行されることがあります。処理対象のitem数を確認する習慣が必要です。

JSONとは何か

JSONは、名前と値の組み合わせでデータを表現するテキスト形式です。

{
  "name": "Pump A",
  "pressure_mpa": 10,
  "enabled": true
}

この例には、次の3つのfieldがあります。

JSONでは、値の型を区別します。

{
  "number_value": 10,
  "string_value": "10",
  "boolean_value": true,
  "null_value": null
}

10と"10"は同じではありません。前者はnumber、後者はstringです。数値比較や計算を行うときは、値だけでなく型も確認します。

field、object、arrayの違い

field

fieldは、名前と値の組み合わせです。

{
  "pressure_mpa": 10
}

ここではpressure_mpaがfield名、10が値です。

object

objectは、複数のfieldをまとめた構造です。波括弧{}で表します。

{
  "machine": {
    "name": "Press A",
    "location": "Line 1"
  }
}

machineの値もobjectであり、その内側にnameとlocationがあります。このような構造をnested objectと呼びます。

array

arrayは、複数の値を順序付きでまとめた構造です。角括弧[]で表します。

{
  "tags": ["hydraulic", "maintenance", "inspection"]
}

ここで重要なのは、itemのarrayと、item内のfieldとして存在するarrayは別物だという点です。

[
  {
    "json": {
      "name": "Pump A",
      "tags": ["hydraulic", "pump"]
    }
  }
]

この例は1 itemです。tagsに2要素ありますが、2 itemsではありません。

1 itemと複数itemsの違い

1 item

[
  {
    "json": {
      "name": "Pump A"
    }
  }
]

外側のarrayにobjectが1つあるため、1 itemです。

3 items

[
  { "json": { "name": "Pump A" } },
  { "json": { "name": "Valve B" } },
  { "json": { "name": "Cylinder C" } }
]

外側のarrayにobjectが3つあるため、3 itemsです。

1 itemの中に3要素のarrayがある

[
  {
    "json": {
      "names": ["Pump A", "Valve B", "Cylinder C"]
    }
  }
]

これは1 itemです。names fieldの値が3要素のarrayになっています。

この違いは、後続nodeの実行回数やデータ変換方法に影響します。

INPUTとOUTPUTの関係

nodeは前のnodeのOUTPUTをINPUTとして受け取り、処理後のデータをOUTPUTとして渡します。

Node A OUTPUT
→ Node B INPUT
→ Node B OUTPUT
→ Node C INPUT

たとえば、Edit Fields nodeが各itemへchecked fieldを追加するとします。

入力：

[
  { "json": { "name": "Pump A" } },
  { "json": { "name": "Valve B" } }
]

出力：

[
  {
    "json": {
      "name": "Pump A",
      "checked": true
    }
  },
  {
    "json": {
      "name": "Valve B",
      "checked": true
    }
  }
]

確認するときは、「値が変わったか」だけでなく、次も確認します。

• item数は変化したか
• fieldが追加・削除されたか
• 値の型は変化したか
• nested objectやarrayの形は維持されたか

Table表示とJSON表示を対応付ける

n8nのINPUT／OUTPUTでは、データをTable形式やJSON形式で確認できます。利用環境やデータ内容によって表示できる形式は異なる場合があります。

Table表示は、各itemを行、fieldを列として確認するのに適しています。

JSON表示では、データ型、nested object、arrayなどの構造を正確に確認できます。

[
  {
    "name": "Pump A",
    "pressure_mpa": 10,
    "enabled": true
  },
  {
    "name": "Valve B",
    "pressure_mpa": 14,
    "enabled": false
  }
]

Table表示は一覧性に優れますが、複雑な入れ子構造では全体像を把握しにくくなります。値が取得できないときや型が疑わしいときはJSON表示へ切り替えます。

$jsonは何を指すのか

n8nのExpressionでは、現在処理しているitemのJSONデータを$jsonで参照できます。

現在のitemが次の内容だとします。

{
  "name": "Pump A",
  "pressure_mpa": 10
}

nameを参照するExpressionは次のようになります。

{{ $json.name }}

pressure_mpaを参照する場合は次のとおりです。

{{ $json.pressure_mpa }}

複数itemsが入力された場合、$jsonは固定された1件ではなく、そのnodeが現在処理しているitemを指します。

item 1を処理中 → $json.name は Pump A
item 2を処理中 → $json.name は Valve B
item 3を処理中 → $json.name は Cylinder C

そのため、同じExpressionを設定しても、各itemに対応した値を取得できます。

nested objectの値は、たとえば次のように参照します。

{{ $json.machine.name }}

実際にはINPUT panelからfieldをドラッグ＆ドロップしてExpressionを作成することもできます。最初は手入力だけに頼らず、生成された参照式と元データのpathを対応付けると理解しやすくなります。

item linkingという仕組み

n8nは、出力itemと、その元になったinput itemの対応をmetadataで管理します。これをitem linkingと呼びます。

通常のnodeではn8nが対応を処理しますが、itemsの分割・結合・並べ替えやCode nodeでの新規生成では意識が必要になる場合があります。

Day 3では「Expressionは現在のitemと対応する元itemをたどれる」と理解できれば十分です。

binary dataはJSONとは別に扱われる

画像、PDF、音声などのファイルはbinary dataです。

n8nのitemは通常データ用のjsonとは別にbinary領域を持てます。Day 3では、ファイル本体と、それを説明するファイル名や処理状態などのJSON fieldは別に扱われる、と理解しておきます。

よくある混乱

• itemとJSON objectを同一視する：itemは処理単位で、通常データはjson内にあります。
• field内のarrayを複数itemsだと思う：arrayの要素数とitem数は別です。
• $jsonをWorkflow全体だと思う：基本的に現在処理中のitemを指します。
• Tableだけで型を判断する：JSON表示で引用符、{}、[]を確認します。
• 古いOUTPUTを見る：設定変更後は再実行し、対象executionを確認します。

複数itemsを観察する最小Workflow

実習では、次の構成が分かりやすいでしょう。

Manual Trigger
→ Code（3 itemsのfixtureを作る）
→ Edit Fields（各itemへfieldを追加）

Code nodeでは、検証用として次の3 itemsを返します。

return [
  { json: { name: 'Pump A', pressure_mpa: 10 } },
  { json: { name: 'Valve B', pressure_mpa: 14 } },
  { json: { name: 'Cylinder C', pressure_mpa: 7 } },
];

このコードを暗記する必要はありません。今回は複数itemsを用意するfixtureとして使います。

次のEdit Fieldsで、Boolean型のchecked fieldを追加します。

checked = true

3 input itemsのそれぞれにcheckedが追加され、3 output itemsになるかを確認します。その後、1件だけpressure_mpaの値を変更し、JSON表示とTable表示の両方で差を確認します。

実務での考え方

実務ではnodeの数より、入力field、型、item数、出力での変更というデータ契約を意識します。

input:
  item_count: "one_or_many"
  required_fields:
    - name
    - pressure_mpa

output:
  added_fields:
    - checked
  preserves_item_count: true

入出力を決めておけば、Workflowが長くなってもnode間の責務を追跡できます。外部システムへ接続する場合も、先に入出力JSONを固定すると検証しやすくなります。

今日の実習で確認すること

• 3件以上のitemsを用意する
• OUTPUTのitem数を確認する
• Table表示とJSON表示を切り替える
• 各itemへchecked fieldを追加する
• 入力と出力でitem数が維持されるか確認する
• 1件だけ値を変えて出力差を確認する
• $jsonが現在処理中のitemを指すことを説明する
• 記事と実際のUIに差があれば記録する

実習結果は次のように記録できます。

input_item_count: 3
output_item_count: 3

added_field:
  name: checked
  type: boolean

changed_item:
  name: "observed item name"
  before: "observed value"
  after: "observed value"

json_reference_understanding: true_or_false
ui_differences: []
questions: []

まとめ

n8nは、nodeを並べるだけのツールではありません。itemsのarrayがnode間を移動し、それぞれのnodeが現在のitemを処理するデータフローシステムです。

items
→ nodeのINPUT
→ item単位で処理
→ nodeのOUTPUT
→ 次のnodeのINPUT

通常データは各itemのjson内にあり、fieldは名前と値の組み合わせです。objectは{}、arrayは[]で表されます。

$jsonは現在処理中のitemのJSONデータを参照します。Table表示で一覧を見て、JSON表示で型と入れ子構造を確認する習慣をつけると、後続のData MappingやExpressionsを理解しやすくなります。

参考資料

• n8n公式：Understand n8n’s data structure
• n8n公式：Reference data
• n8n公式：How items link through workflows
• n8n公式：Work with files and images