json-filter (Transform Node)

The JSON Filter node applies a JMESPath  expression to JSON emitted by an upstream node and returns only the selected subset.

Use this node as a generic JSON shaping/filtering step before downstream transforms or dashboard nodes.

Configuration Schema

Notes:

• json-filter accepts a single input (acceptsMultipleInputs: false).
• Configuration requires expression and disallows additional properties.

How it works

At runtime, the processor:

1. Fetches latest upstream input (fetch_latest_inputs).
2. Takes the first payload from the input map.
3. Parses payload as JSON.
4. Evaluates jmespath.search(expression, parsedJson).
5. Returns the filtered value for runtime output persistence.

Output can be an object, array, scalar, or boolean, as long as it is JSON-serializable.

Example

Input JSON:

[
  { "userId": "u1", "score": 10, "status": "green" },
  { "userId": "u2", "score": 15, "status": "amber" },
  { "userId": "u1", "score": 20, "status": "green" }
]

Node configuration:

{
  "expression": "[?userId=='u1']"
}

Output JSON:

[
  { "userId": "u1", "score": 10, "status": "green" },
  { "userId": "u1", "score": 20, "status": "green" }
]

Example configuration patterns

Filter by session-scoped user:

{
  "expression": "records[?userId=='$SESSION.userId']"
}

Select first item from a list:

{
  "expression": "* | [0]"
}

Project specific fields into a compact shape:

{
  "expression": "events[].{time: timestamp, value: metrics.score}"
}

Runtime failure behavior

The node fails intentionally in the following cases:

• No upstream input is available.
• expression is missing from configuration.
• Input payload cannot be parsed as JSON.
• JMESPath evaluation raises an error.
• JMESPath completes but returns null / no match (filtered is None).

Important behavior notes:

• Empty list ([]) is not None, so the processor returns it. Downstream runtime handling may still treat empty outputs as failure depending on core runtime rules.
• Validation requires expression to be a string.

Integration in a session template

1. Place json-filter after any node that outputs JSON.
2. Configure expression to select the exact structure downstream nodes need.
3. Connect downstream nodes (for example dashboard or dashboard-v2) to consume the filtered payload.
4. Reuse the same node pattern across projects by changing only JMESPath expressions.

Related concepts

• Dashboard Tools Runner
• Node Templates
• JMESPath