This page is part of archived documentation for openHAB 3.3. Go to the current stable version

# JsonPath Transformation Service

Extracts values from a JSON string using a JsonPath (opens new window) expression.

Given the following JSON string:

[{ "device": { "location": "Outside", "status": { "temperature": 23.2 }}}]

The expression $.device.location extracts the string Outside. The JsonPath expression $.device.status.temperature extracts the string 23.2.

# Examples

# Items

String  Temperature_json "Temperature [JSONPATH($.device.status.temperature):%s °C]" {...}
Number  Temperature "Temperature [%.1f °C]"

# Rules

rule "Convert JSON to Item Type Number"
  when
    Item Temperature_json changed
 then
    // use the transformation service to retrieve the value
    val newValue = transform("JSONPATH", "$.device.status.temperature", Temperature_json.state.toString)

    // post the new value to the Number Item
    Temperature.postUpdate( newValue )
 end

Now the resulting Number can also be used in the label to change the color (opens new window) or in a rule as a value to compare.

# Differences to standard JsonPath

Compared to standard JsonPath, the transformation returns single values instead of arrays. The transformation also will not ever return null. This makes it possible to use the transform in labels or output channels of Things.

If the JsonPath expression provided results in no matches, the transformation will return the entire original JSON string.

# Usage as a Profile

The transformation can be used in a Profile on an ItemChannelLink too.

One example for configuring it in the .items file:

String <itemName> { channel="<channelUID>"[profile="transform:JSONPATH", function="<jsonPath>", sourceFormat="<valueFormat>"]}

The JsonPath expression to be used has to be set in the function parameter. The parameter sourceFormat is optional and can be used to format the input value before the transformation, i.e. %.3f. If omitted, the default is %s, so the input value will be returned from the transformation without any format changes.

This profile is a one-way transformation; only values from a device toward the item are changed.

# Further Reading

An extended introduction (opens new window) can be found at W3School.
As JsonPath transformation is based on Jayway (opens new window), using an online validator (opens new window) which also uses Jayway will give the most similar results.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Jinja Map →