[SOLVED] Item metadata


I have read the documentation about item metadata, but for me it isn’t clear. Will appreciate more explanation.

This is an example:

Switch TestSwitch "Test Switch" ["foobar"] {foo="bar" [baz=42]}
  1. What does the foo means?
  2. What does the bar means?
  3. How the data inside [] relates to foo="bar?
  4. Metadata and channel information are in the same bracket {}?


The doc you linked to isn’t especially clear to me, but it appears that:

  • foo is a key in the binding configuration
  • bar is the value associated with foo
  • baz is a key in the metadata for foo
  • 42 is the value associated with baz

Presumably it would be up to each binding/service to determine how to use the “metadata” (which I’m also assuming is the data in the last set of square brackets).

Here’s the example from the document:

Switch "My Fan" { homekit="Fan.v2", alexa="Fan" [ type="oscillating", speedSteps=3 ] }

It’s not clear to me which parts of the example in the document are considered metadata, nor which parts are considered a namespace.


First, thx for you respobse

But Item can be without binding … Might it be that foo is the name space?

For this purpose, such meta-information can be attached to Items using disjunct namespaces so they won’t conflict with each other


I cannot get item metadata from REST API. Was this issue fixed?

Switch Test { foo="bar" [baz=43] }

  "link": "",
  "state": "NULL",
  "editable": false,
  "type": "Switch",
  "name": "Test",
  "tags": [],
  "groupNames": []

You need to add metadata info in the query:

In your example,

foo = namespace, “bar” = the value for that namespace

[baz=42] is the configuration, a list of key/value pairs for that namespace.

In OH, most metadata is used for linking an item to a binding via the channel namespace.

You can easily read/write metadata from jython. Rules DSL does not support easy access to metadata.

@vzorglub @mjcumming

Thx! now I see the data. It also explains how the data is stored although I am not sure I fully understand why the name space has a value (as u can set a key/value for that. But never mind, for me now it is enough to start using metadata. I will search for Jython code to use the metadata.

Thx for you help!

The fact that namespace has a Value is totaly not logcial for me since it looks like you cant change that value.

But the real question is how do I update a metadata value with REST?
I need to hold 2 custom values for my custom User Interface and can read them when I define them in the items file

  "metadata": {
    "UIsetup": {
      "value": "blah",
      "config": {
        "xpos": 15,
        "ypos": 44

I try to do do REST PUT to

with the following body

  "value": "blah",
  "config": {"xpos" :  99}

It will not update (despite I get response code 200 OK) nor it will allow adding new config fields

does the fact that item returns

`“editable”: false

has anything to do with it?

After further investigation I see I can add the new namespace metadata IF it was NOT defined with the Item definition, Those defined in the Items file are Read Only.

Another question is then what happens with the metadata after the OH reboot are they lost? or last state is recalled? from somewhere?

That’s it.
The “cure” is to create your Item using PaperUI, not xxx.items file.

I’m fairly certain that as the Item is created anew from xxx.items file, you get a crisp new copy of what is in the file. Nothing retained from previous boot.

If however your Item is originally created with PaperUI, this is saved to the internal JONDB store … as are any subsequent edits.

Ok so its not a bug its a Feature.

And if I do create and Item with the REST API will it go into that JONDB internal DB?
I need to batch create 250 sensors so just batch creating an items file was my option but I can do that with the rest interface as well if that is now the “better” way of storing Items. I’m just afraid that if I have to change the architecture it would be a major PITA to batch edit.

That is exactly what PaperUI and Habmin do, they use the REST API, so will behave exactly the same.
Typo: behind this is a JSONDB store. Readable, but ill-advised to directly edit.

The choice of PaperUI/REST is up to you. I use xxx.items files because they are easy to organize, edit and review. But I’ve no need of dynamic alterations.

yes, files are easier.
I develop custom map UI and need to store somehow info about the position of the sensor on the floorplan SVG basicly only 3 parameters x, y, floorplan name

I wanted to do that with metadata, but it might be that I will create companion Items to store those values as state, what do you think?

It’s really up to you.

If you add to metadata, bear in mind others can as well. Some future general enhancement may interfere with your private scheme.

Or you may be planning to publish your solution for all, in which case you probably wish to include your changes in the general OH scheme of things. I don’t know what standards should be followed for that.

There may already be a scheme or proposal for recording physical Thing location that is adaptable, I’ve no idea. Location sounds to me more like a property of a Thing, a representation of a physical device. The counter argument is that location-on-a-map is an abstract property of an abstract Item. Dunno about that, since a Thing (e.g. sensor box) may have many Items (temp, humid, lux, etc) with one location.

My gut says not to mess with existing data structure outside of OH development, because you’d be at the mercy of changes outside of your control. I’d use some private storage keyed by Item or Thing name. That could take the form of additional Items of course.

I’m totally guessing here, but is the issue that you are trying to change a setting via the openhab.org portal, rather than directly to the Local IP address?

I know that you can’t delete items via the Cloud connection… for example

Hi all

I’m trying to get my head around the whole Metadata namespace thing via RESTapi this afternoon and after 3 attempts with Google, nothing has changed.

I think adding Metadata via the RESTapi interface might be where I am going wrong.

As a work in progress, this is what I’m doing / have done so far

Created a Thermostat Group and added the following members

  • Current Temperature
  • Current Setpoint
  • Thermostat Mode

Added the following Metadata to the Thermostat Group Item in RestAPI

namespace = ga

body =

  "value": "Thermostat",
  "config": {}

Added the following Metadata to the Current Temperature Item

namespace = ga

body =

  "value": "thermostatTemperatureAmbient",
  "config": {}

Added the following Metadata to the Current Target (Setpoint) Temperature Item

namespace = ga

body =

  "value": "thermostatTemperatureSetpoint",
  "config": {}

Added the following Metadata to the Thermostat Mode Item

namespace = ga

body =

      "value": "thermostatMode",
      "config": {}

Also tried defining the Mode names like this for a Velbus Thermostat

namespace = ga

body =

      "value": "thermostatMode",
      "config": {modes="off=SAFE,heat=COMFORT,eco=NIGHT,on=DAY"}

1 Like

I’m trying to add Alexa metadata to an item created in Paper UI using REST API. I have succeeded in adding Alexa Metadata to an Item created in a .items file, but am I having trouble doing it with the REST API.

I get a Response Code 200 (OK), but when I have Alexa search for new devices, nothing shows up.

Any ideas?


try to write alexa in small letters; alexa


Thanks. That was easy. With lower case the return code is 201 (Created), and Alexa recognized the new device.