Skip to content

Paths and Behavior

Arie J. Godschalk edited this page Nov 15, 2026 · 1 revision

Paths and behavior

Home › Paths and behavior

Contents

Read paths

A path tells Read JSON where to find a value. Given:

{
  "room": {"name": "Kitchen"},
  "words": ["red", "blue"],
  "Total volume": 12,
  "switch:0": {"on": false}
}

Use room.name for Kitchen, words[0] for red, and words[1] for blue. A path without a root is prefixed automatically. Total volume works as a single property name. For punctuation or ambiguous names, use explicit bracket notation such as $['switch:0'].on. The equivalent explicit root form is $.room.name. Names and case must match exactly.

Read uses the jsonpath library, not jq or JavaScript expressions. Its value method returns the first match, not a list of all matches. For example $.words[*] returns red. Choose a path to a scalar of the token's matching type. An object, array, null or a value of another type may be rejected by Homey.

Build paths

Build uses a different, simpler dot-split writer, not JSONPath. On a new empty object, room.name creates an object containing a name. Do not use $, bracket notation or an array index for writing: for example words[0] becomes a literal property name, not an array item. To insert an entire array or object, use a Build JSON (Json's) card.

Important current limitation: if an intermediate property already exists and is truthy, the writer does not descend into it. For example, starting with {"room":{"name":"Kitchen"}}, writing room.temperature puts temperature at the root, not in room. The same can happen when two inputs in one card share a parent. Test the output before relying on nested updates. Use a whole nested object as a JSON value or another JSON-aware tool for reliable modifications. Falsy existing intermediate values can be replaced by an object. Empty paths and null/undefined input values are skipped; false, 0 and an empty text value can be written when supplied.

Defaults and types

For Read, an empty path returns one space for text, 0 for number, or false for yes/no. A path that throws a JSONPath parsing error also uses the corresponding default. A valid path that finds no match instead returns JavaScript undefined; Homey can reject that as an invalid typed token. A present null or wrong type is not converted to the requested type either. Use a separate card for optional fields, handle its error, and do not assume zero means the property was found.

Build accepts empty Existing JSON as a new {}; Read requires valid JSON input. Invalid JSON causes an action error. For Build, supply an object as the root for predictable property writes. It serializes the result with JSON.stringify; the original text token is not changed. If several assignments target the same location, later assignments win, in text, then number, then yes/no order. JSON-value cards process their numbered inputs in order. A blank JSON-value field is skipped; a nonempty one must itself be valid JSON.

Arrays and multiple matches

Read a known item with [0] or words[0]. For every item, use the two loop cards. JSON Handler's builder is not an array append or removal tool. For storing and editing lists, see Better Logic Library's list guide. Its rules and inputs differ from this app's Build paths.

Clone this wiki locally