JsonParser

The JSON Parser operation extracts values from a JSON input using JSON Pointer (RFC 6901) expressions. Each configured pointer maps to a separate output, allowing a single JSON document to be destructured into up to 20 individual values.

Inputs

Port	Type	Required	Description
In	String | Binary | Map | Array	Yes	JSON text, or a Map or Array that is already the document — the failure record on an error output is one. A pointer resolves the same way over either. Binary input is treated as UTF-8 text; non-UTF-8 bytes fail the Node, and its On Error verb resolves the failure.

Outputs

Port	Type	Default	Description
Out (variable, up to 20)	User-configurable	Nil	Extracted value for each configured JSON Pointer. Missing paths resolve to Nil. Accepted MessagePack types for each Out port are set in the Node’s Settings panel — see Setting Port Types.

Properties

Name	Type	Default	Description
Schema	TextBox (multi-line)	""	JSON Pointer configuration. Each line maps an output number to a pointer, e.g. 1 /data/name.
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

State on Reload

All outputs are preserved across restarts within the configured time window. Saved state is discarded if the number of outputs changed, or if any output’s configured JSON pointer changed. In that case outputs start empty until the next run.

---

Schema Format

Each line in the Schema property follows the pattern:

<output_number> <json_pointer>

Example:

1 /data/name
2 /data/age
3 /items/0

Output numbers are 1-based (matching the visible port labels in the UI).

Pointers follow the RFC 6901 specification: they start with / and use / to separate keys. Array elements are accessed by numeric index. Use ~0 to escape ~ and ~1 to escape / in key names.

Type mapping

JSON values are converted to MessagePack types automatically: true/false → Boolean, number → Number, string → String, array → Array, object → Map, null → Nil.

---

How It Works

1. Input — A String is JSON text; a Binary is JSON text when its bytes form valid UTF-8; a Map or an Array is already the document. Nil, non-UTF-8 Binary, or any other type that slips past the port mask invokes the On Error verb.

2. Document — JSON text is parsed into an in-memory JSON structure; a Map or an Array is walked as it is, with no text made on the way. A parse failure logs a runtime error and invokes the On Error verb.

3. Extract — For each valid line in the Schema, the JSON Pointer is applied to extract a value from the document, whichever road it came by. Pointers that resolve to a missing path produce Nil on that specific output (this is per-pointer behaviour and is not an error).

4. Output — Extracted values are written to their corresponding outputs.

Reading a failure record

Wire an error output into In and give each Output a pointer into the record: /message for the sentence, /code, /severity and /node for a Condition to branch on, /details/0 for the first argument. No text is made on the way: the record arrives as a Map and is walked as one.

---

Examples

Data format

All inputs and outputs use MessagePack internally. The examples below show values in JSON notation for readability.

Basic Extraction

Schema:

1 /data/name
2 /data/age
3 /data/address

In: { "data": { "name": "Alice", "age": 30, "address": "123 Main St" } }

Output	Value
Out 1	"Alice"
Out 2	30
Out 3	"123 Main St"

Nested Access

Schema:

1 /user/profile/name
2 /user/profile/details/age

In: { "user": { "profile": { "name": "Bob", "details": { "age": 25 } } } }

Output	Value
Out 1	"Bob"
Out 2	25

Missing Path

Schema:

1 /data/name
2 /data/email

In: { "data": { "name": "Charlie" } }

Output	Value
Out 1	"Charlie"
Out 2	Nil

The /data/email path does not exist, so Out 2 is Nil.

---

Use Cases

• Extracting specific fields from API responses or MQTT payloads
• Parsing structured log data or configuration files
• Splitting a complex JSON message into individual values for downstream processing

---

Error Handling

JSON Parser can hit these errors: an unconnected input, a Nil or non-UTF-8-Binary input (the Type mask catches most of these earlier), or a top-level JSON parse failure.

Any of these triggers the On Error verb you picked. See the Error Handling guide for the common On Error model; JSON Parser’s options are:

Verb	What it does
Stop this branch (default)	This Node and its dependents stop; Out keeps its value and reads as a failed update.
Continue with the last value	Dependents run on the value Out already holds, not stamped as new; it reads as a failed update.
Continue with the fallback	Dependents run on Out’s per-output Fallback, stamped as this run’s value; it reads as a failed update. The Editor refuses a Task where the Fallback is unset.

Each JSON Parser output carries its own per-output Fallback value (Settings panel, under the output port). Continue with the fallback writes each output’s Fallback on a top-level parse failure.

Note the distinction between a top-level parse failure (the whole input is not valid JSON — this is an error and the Node’s On Error verb resolves it) and a missing pointer in a valid document (the JSON parses fine but one of your Schema pointers doesn’t resolve — this is not an error, and that specific output gets Nil).

---

Limitations

• Up to 20 configurable outputs (numbered 1–20 in the Schema property).
• Each JSON Pointer must start with / as per RFC 6901.
• Schema lines are validated at compile time: invalid output numbers or malformed pointers are reported as errors.