JSON Loop Open¶
Iterates over a JSON array and emits the current item alongside up to four auxiliary data streams. It drives a JSON loop by producing a LOOP status object and the item at the current index, while honoring a user-defined condition that determines whether the iteration should proceed.
Usage¶
Use this node to process each element of a JSON array step-by-step. Provide a JSON array string, connect the LOOP output to a JSON Loop Close node, and consume current_item for per-item processing. Use aux outputs to carry state across iterations (e.g., accumulators). Control loop flow with the condition expression, and optionally jump to a specific position with index_override.
Inputs¶
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| json_list | True | STRING | The JSON array to iterate over. Must parse to a list when treated as JSON. | ["item1", {"name": "item2", "active": true}, 3] |
| condition | True | STRING | A boolean expression evaluated each iteration to decide whether to run the iteration. You can reference loop variables such as current_item, current_index, index, finished, total_items, and items. | current_index < total_items and (not finished) |
| index_override | False | any | Manually set the current index (0-based) for this iteration. Negative or invalid values are sanitized to 0. | 3 |
| aux | False | any | Primary auxiliary data that travels with the loop for maintaining state across iterations. | {'sum': 0, 'count': 0} |
| aux2 | False | any | Secondary auxiliary data passed through each iteration. | ['seen', 'values'] |
| aux3 | False | any | Tertiary auxiliary data passed through each iteration. | running_state_token |
| aux4 | False | any | Quaternary auxiliary data passed through each iteration. | {'buffer': []} |
Outputs¶
| Field | Type | Description | Example |
|---|---|---|---|
| LOOP | any | A status dictionary describing the loop state. Connect this to the LOOP input of a JSON Loop Close node. | {'id': 123456, 'items': ['a', 'b', 'c'], 'index': 0, 'finished': False, 'total_items': 3, 'last_id': ' |
| current_item | any | The current element from the JSON array at the active index. | item1 |
| aux | any | Pass-through of the primary auxiliary data for this iteration. | {'sum': 5, 'count': 2} |
| aux2 | any | Pass-through of the secondary auxiliary data for this iteration. | ['seen', 'values', 'item1'] |
| aux3 | any | Pass-through of the tertiary auxiliary data for this iteration. | running_state_token |
| aux4 | any | Pass-through of the quaternary auxiliary data for this iteration. | {'buffer': ['item1']} |
Important Notes¶
- Condition is a string expression evaluated each iteration. Available variables include current_item, current_index (0-based), index (alias of current_index), finished, total_items, and items.
- json_list must represent a JSON array. If parsing fails or the value is not a list, the node will not emit data for that pass and the loop will not advance.
- index_override is coerced to a non-negative integer. If it points beyond the end of the list, the loop is marked finished on the next interaction with the Close node.
- finished becomes true on the last valid item or when the end of the array is reached; the Close node uses this to determine loop completion.
- Auxiliary values (aux, aux2, aux3, aux4) are simply passed through each iteration so downstream nodes can carry state forward.
Troubleshooting¶
- Invalid JSON in json_list: Ensure the input is a valid JSON array string (e.g., [1,2,3]). If invalid, fix the JSON or supply a pre-parsed list via an upstream node.
- Condition errors or unexpected False: If your condition references keys not present in current_item or variables not defined, it may evaluate to False. Adjust the condition or guard with checks (e.g., isinstance or key presence).
- No outputs on a pass: This can happen if condition evaluates to False or json_list is invalid. Verify both inputs and the current index.
- Loop never finishes: Confirm that index_override is not repeatedly resetting to a prior index, and that your condition does not keep preventing progression.
- current_item is unexpected type: Verify your JSON array contents. Mixed types are supported, but your downstream logic should handle the item type accordingly.
- Close node does not signal completion: Ensure the LOOP output from this node is connected to the JSON Loop Close node, and that the list and condition allow iteration to reach the end.