node-red-contrib-json

0.2.0 verified Sat May 09 auth: no javascript maintenance

A Node-RED node for processing JSON objects using multiple query engines: JSONSelect, JSONPath, jq, and json-select. Current stable version is 0.2.0. Release cadence is irregular; this package is in early maintenance mode. Key differentiators include support for multiple query languages in one node and the ability to choose between lightweight (JSONSelect) and powerful (jq) engines. The jq engine requires the jq command-line tool to be installed separately, which is a notable dependency compared to pure JavaScript alternatives. The node integrates into Node-RED's flow-based programming environment, allowing visual wiring of JSON transformations.

Common errors

error Error: Cannot find module 'node-red-contrib-json' ↓

cause Node-RED cannot find the installed package, or the package was installed in the wrong directory.

fix

Install the package in your Node-RED user directory (usually ~/.node-red): cd ~/.node-red && npm install node-red-contrib-json

error Input payload must be a valid JSON object ↓

cause The node expects msg.payload to be a JSON object, but receives a string or other type.

fix

Use a JSON parse node before this node to convert strings to objects.

error jq: command not found ↓

cause The jq command-line tool is not installed or not in PATH.

fix

Install jq from https://stedolan.github.io/jq/ and ensure it is available in the system PATH.

Warnings

gotcha jq engine requires the jq command-line tool to be installed separately; if not found, the node may fail silently or produce no output. ↓

fix Install jq from https://stedolan.github.io/jq/ and ensure it is in your system PATH.

gotcha The JSONSelect engine uses recursive descent by default (like CSS), which may produce unexpected results if you are not familiar with the syntax. ↓

fix Use the '>' combinator for direct children, e.g., '.foo > .bar' instead of '.foo .bar'.

gotcha Output format varies by engine: JSONSelect and JSONPath return arrays; jq returns one message per result (possibly multiple messages); json-select returns the result directly (may be array). ↓

fix Check the engine documentation and handle output accordingly; use a Node-RED function node to convert if needed.

gotcha The node modifies msg.payload only; other properties of the message are passed through unchanged. ↓

fix If you need to preserve original payload, store it in another property before this node.

Install

npm install node-red-contrib-json

yarn add node-red-contrib-json

pnpm add node-red-contrib-json

Imports

contrib-json

wrong

require('node-red-contrib-json')

correct

Node-red node, installed via npm package 'node-red-contrib-json'. No JavaScript import needed; add node from Node-RED palette.

This is a Node-RED contrib node, not a library. It is used by adding the 'contrib-json' node from the Node-RED palette after installation.

Quickstart

Shows installation, configuration, and usage of the contrib-json node with JSONSelect engine.

Install the package in your Node-RED user directory:
npm install node-red-contrib-json
Then restart Node-RED and add a 'contrib-json' node from the palette. Configure it by selecting an engine (e.g., JSONSelect) and an expression (e.g., '.foo'). Wire input and output nodes. Deploy and send a message with msg.payload = {"foo": "bar"}. The output msg.payload will contain ["bar"] as an array.