Repository navigation
Paths and Behavior
Home › Paths and behavior
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 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.
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.
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.
Support development - If JSON Handler is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!