Skip to Content
This documentation is provided with the HEAT environment and is relevant for this HEAT instance only.
RunnersCore UtilsJSON Flatten Node

json-flatten (Transform Node)

The JSON Flatten node takes a single JSON input and flattens it into a wide tabular format (CSV or TSV). You can optionally target a specific array via a JMESPath expression (root); nested objects become dotted column names (e.g. a.b.c), and arrays can be expanded by index (key.0, key.1) or joined into a single column.

Use this node when you need to turn nested JSON (e.g. from an API or a previous transform) into rows and columns for analytics, CSV export, or downstream tabular nodes like tabular-query or tabular-remap.

Configuration Schema

PropertyTypeRequiredDescription
rootstringNoJMESPath expression that selects the array to flatten. If empty or omitted, the entire input is treated as the root (must be array-like). Defaults to "".
outputFormat"csv" | "tsv"NoDelimiter for the output. Defaults to csv.
separatorstringNoCharacter used to join nested keys into column names (e.g. a.b.c). Defaults to ".".
arrayHandling"index" | "join"NoHow to represent arrays: index produces columns like key.0, key.1; join produces one column with values joined by arrayJoinSep. Defaults to index.
arrayJoinSepstringNoUsed when arrayHandling is join. Defaults to `"
includearray<string>NoOptional whitelist of dotted paths (JMES-like) to include. If empty, all paths are included.
excludearray<string>NoOptional blacklist of dotted paths to exclude.
nullValuestringNoString to emit for null/missing values. Defaults to "".
castNumbersbooleanNoWhen true, emit numbers as plain strings without trailing .0 where possible. Defaults to true.

Behaviour

  • The node parses the upstream payload as JSON.
  • If root is set, it evaluates the JMESPath expression and uses the result as the set of rows to flatten. The result must be array-like; each element is typically an object.
  • If root is empty, the whole input is used (and must be an array of objects, or a single object treated as one row).
  • For each row (object), nested keys are flattened into column names using separator (e.g. user.name → column user.name). Arrays are handled according to arrayHandling.
  • The include and exclude lists filter which columns appear in the output.
  • All values are stringified for CSV/TSV; nullValue is used for nulls or missing keys.

Example configuration

{
  "root": "items",
  "outputFormat": "csv",
  "separator": ".",
  "arrayHandling": "index",
  "arrayJoinSep": "|",
  "nullValue": "",
  "castNumbers": true
}

Input (excerpt):

{
  "items": [
    { "id": 1, "user": { "name": "Alice", "role": "driver" } },
    { "id": 2, "user": { "name": "Bob", "role": "observer" } }
  ]
}

Output CSV:

id,user.name,user.role
1,Alice,driver
2,Bob,observer

Integration in a session template

  1. Place a json-flatten node after any node that emits JSON.
  2. Set root to the JMESPath for the array to flatten (e.g. items, data.rows), or leave empty to flatten the whole input.
  3. Choose outputFormat, arrayHandling, and optional include/exclude to shape the table.
  4. Connect downstream nodes (e.g. tabular-remap, tabular-query, or dashboard tools) to consume the CSV/TSV.
Hydrate Protobuf NodeJSON Template Node