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
inputMode"all" | "latest"NoInput selection policy. all enumerates all available parent outputs (can duplicate rows if parents emit cumulative snapshots). latest uses only the most recent parent output. Defaults to all.
jsonInputFormat"json" | "ndjson"Nojson (default): parse the whole payload as a single JSON value, then apply root. ndjson: UTF-8 JSON Lines (newline-delimited JSON): each non-empty line is one complete JSON value, parsed with json.loads independently; root is evaluated per line. Use root empty when each line is already one row object (typical for hydrate-protobuf SimulationFrame output with lineDelimitedJson).
rootstringNoJMESPath expression that selects the array to flatten. If empty or omitted, the entire input is treated as the root (must be array-like in json mode). In ndjson mode, an empty root selects the whole line object as one row. 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

  • Input selection (inputMode):\n - Default (all): the node enumerates all available upstream outputs and selects the first payload in that enumeration.\n - latest: the node uses only the latest upstream output.\n - When to use latest: when the parent node outputs cumulative snapshots over time (for example, repeated hydrate runs where later outputs contain all earlier data). Using latest avoids reprocessing earlier partial snapshots and reduces duplicated rows.\n+
  • Note on multi-output parents: inputMode: "all" enumerates outputs and some runtime paths return a list of payloads for a single parent (one per upstream output). In that case, this node selects the first payload in that list.
  • The node parses the upstream payload according to jsonInputFormat (default single-document JSON).
  • In ndjson mode, each non-empty line must be one complete JSON value (often one object). Pretty-printed JSON with newlines inside a single array is not NDJSON; use json mode with a streaming parser upstream or keep one JSON document.
  • If root is set, it evaluates the JMESPath expression and uses the result as the set of rows to flatten (or, in ndjson, the result per line). In json mode the result must be array-like; each element is typically an object.
  • If root is empty, the whole input is used in json mode (and must be an array of objects, or a single object treated as one row). In ndjson mode, each line object is 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 v2 NodeJSON Template Node