[OH3] Semantic Model setup via tags in configuration Items files


If you are unsure of what the Semantic Model is, or what it can do for you in openHAB 3, then check the documentation here.

This post is my notes on creating a Semantic Model via the configuration files (*.items files), rather than the UI.


I read this post, and used this list in order to work this all out.


The Semantic Model is made up of Items with extra bits of information tagged on to them. These extra bits of information tell openHAB a little bit more about what the Item is, such as whether it is a Location, an Equipment, a Property or a Point.

You can tag existing Items, or create new ones.


Locations within the Semantic Model are Group Items tagged with a specific location tag from the list.

A quick note: Locations within the Semantic Model are not the same as a Location Item.

  • Location Item: a proper Item that holds latitude and longitude values.
  • Location in the Semantic Model: a Group Item tagged with a defined Location from the list.

It is unfortunate that they are both called Location!

Top level Locations

Let’s create a couple of top-level Locations, as follows:


Group gIndoor "Indoor" ["Indoor"]

Group gOutdoor "Outdoor" ["Outdoor"]

Here we have defined two Locations for the Semantic Model: Indoor and Outdoor.

The tag is the ["Indoor"] or ["Outdoor"] part of the Item configuration. The text Indoor or Outdoor must be a valid location tag from the list.

The name of the Group Item itself (gIndoor and gOutdoor above) can be whatever you want. Same with the label.

If the above is saved in a Item configuration file, you will see the following within the Model section of the openHAB 3 UI:

Second level Locations

We can add more Locations within the Indoor and Outdoor Locations as follows:


Group gIndoor "Indoor" ["Indoor"]

Group gGroundFloor "Ground Floor" <groundfloor> (gIndoor) ["GroundFloor"]

Group gFirstFloor "First Floor" <firstfloor> (gIndoor) ["FirstFloor"]

Group gOutdoor "Outdoor" ["Outdoor"]

Group gGarden "Garden" <garden> (gOutdoor) ["Garden"]

We have now added a Ground Floor Location within the Indoor location by:

  • Adding (gIndoor) to the configuration of the Ground Floor Item
  • Adding ["GroundFloor"] tag to the configuration of the Ground Floor Item

Note that there is also a <groundfloor> in the configuration: this defines the icon for this Location, and must be a valid icon name.

Note that all that we’ve been doing is creating Group Items, and defining other Group Items (such as gGroundFloor) as members of higher-level Group Items (such as gIndoor).

The Model in the openHAB 3 UI will now look like below:

Third level Locations

Now lets add a Living Room and Kitchen into the Ground Floor Location. The below is only the addition to the existing configuration from above:

Group gLivingRoom "Living Room" (gGroundFloor) ["LivingRoom"]

Group gKitchen "Kitchen" <kitchen> (gGroundFloor) ["Kitchen"]
See full configuration

Group gIndoor "Indoor" ["Indoor"]

Group gGroundFloor "Ground Floor" <groundfloor> (gIndoor) ["GroundFloor"]

Group gLivingRoom "Living Room" (gGroundFloor) ["LivingRoom"]

Group gKitchen "Kitchen" <kitchen> (gGroundFloor) ["Kitchen"]

Group gFirstFloor "First Floor" <firstfloor> (gIndoor) ["FirstFloor"]


Group gOutdoor "Outdoor" ["Outdoor"]

Group gGarden "Garden" <garden> (gOutdoor) ["Garden"]

We have placed the Living Room on the ground floor (gGroundFloor), and tagged it with the appropriate Location tag ["LivingRoom"]. We have also defined a Kitchen location in the same way.

You can continue to create Locations by defining (or modifying if they already exist) further Group Items, into as many levels as you like - just add the relevant ["Location"] tag!


Now lets create a piece of Equipment that lives in the Living Room. I see Equipment the same way as I see Things - a reference to a single real physical device, such as a relay. And as with Locations, a piece of Equipment is an Item with some extra information to tell openHAB what type of Equipment it is. Normally Equipment will be a Group Item.

In this example I will create two pieces of Equipment: a relay which turns a light switch ON and OFF, and a sensor with temperature and humidity data.

Group gLivingRoomSensor "Living Room Sensor" (gLivingRoom) ["Sensor"]
Group gLivingRoomLight "Living Room Light" <light> (gLivingRoom) ["Lightbulb"]

As with the Locations, pieces of Equipment must be tagged with names from the list - in this case ["Sensor"] and ["Lightbulb"]. Both pieces of Equipment are located in the living room (gLivingRoom).

Note that tagging is done in the same way - adding defined strings in-between square brackets. Because the list of defined names for Locations and Equipment is different, openHAB 3 knows whether your Group Item is a Location or a piece of Equipment.

Points and Properties

Now lets add some points to the Equipment, so that we can do or read something!


For the light we will add the Switch Item which is linked to our relay (in my case via the MQTT Binding). Below is the original Item configuration, pre-OH3.

Switch sLivingRoomLight "Living Room Light" <light> { channel="mqtt:topic:sLivingRoomLight:switch" }

And now with Semantic Model tags:

Switch sLivingRoomLight "Living Room Light" <light> (gLivingRoomLight) ["Switch"]  { channel="mqtt:topic:sLivingRoomLight:switch" }

We have added this Item into the (gLivingRoomLight) Group, so it is now part of the Living Room Light Equipment.

We have tagged the Item ["Switch"]. openHAB 3 now knows this is a Point with a type Switch. Again, we must use the defined Point names from the list.


For the sensor we will add the two Items which hold our sensor information. In my case again this information is coming from the MQTT Binding.

Number nLivingRoomTemperature "Temperature [%.1f°C]" <temperature> (gLivingRoomSensor) ["Measurement", "Temperature"] { channel="mqtt:topic:swLivingRoomShortLight:temperature" }
Number nLivingRoomHumidity "Humidity [%.1f%%]" <humidity> (gLivingRoomSensor) ["Measurement", "Humidity"] { channel="mqtt:topic:swLivingRoomShortLight:humidity" }

Adding to the Sensor Equipment is as before - add (gLivingRoomSensor) to the configuration.

The temperature Item has tags ["Measurement", "Temperature"]:

Logically, we are measuring a temperature at this Point. Similarly, ["Measurement", "Humidity"] for the humidity Item means openHAB 3 knows that we are measuring a humidity at that Point.

Note that it doesn’t matter which way round the Point and Property sit inside the square brackets: ["Measurement", "Humidity"] is the same as [ "Humidity", "Measurement"] as Points and Properties do not share any tag names.


  • Locations = Group Item
  • Equipment = Group Item*
  • Point = Item (single)**
  • Tag = name from the list inside square brackets, at the end of a Group Item configuration, or just before the Channel definition for a single Item.

[*] normally, though theoretically you could tag a single Item with an Equipment tag.
[**] normally, though a Group Item could have a Point tag as long as it also isn’t a piece of Equipment.

Other notes

  • Points do not necessarily have to live in Equipment. A Point can live in a Location just by itself.
  • If part of the Semantic Model was defined and created using the UI you may find that your stuff has lost its position in the model after a restart of openHAB. Recommend that it’s either all UI, or all configuration files, but not a mixture, to reduce unpredictability!

This works fine for me until I restart the OpenHAB service. After that, all textually defined items appear directly on root level of the model.

My suspicion is that somehow the model is not adding the children, because the respective parent equipment groups do not show any group members anymore.

Any idea what I could be doing wrong?

Not without going through your whole configuration, which could be tedious but we can try. I’ve seen reports of a restart of openHAB causing a flat model structure, but I’ve never had that issue. Something to check: is any of your model defined via the UI? That reportedly provides strange results on startup.

Yes, I have started with the general structure by using the UI, thanks for this hint.
I’ll start over by only using text files and see if that helps.

Yep, text only definition works.

I looks to me like the item definition files might be read before the UI-based definitions form the DB are fetched.


I have a question about this. I’m currently building the semantic model with files. I came from OH2.5 so have to add the tags to all the items, and group them better than before.

In OH2.5 I couldn’t add items from one file (e.g. radio.items) to a group which located in another file (e.g. lights.items). I tried this last night, so added a group (gKitchen) to my radio item in the [radio.items] file, but the file didn’t load correctly and the items where NULL, after removing (gKitchen) all was ok again.

Is this just not possible or could I be doing something wrong? I think it’s an bad idea to add all the items in one file to be able to use groups, but maybe i’m wrong there.

1 Like

I have my Items split between different files. Furthermore, almost all my Location Group Items are in a single file called model.items, whilst my Equipment and Points are in various different files - I’ve not had any issues with the separation in files.


I’m gonna try it again these days, will reply if it works (and hopefully why :slight_smile: )

Yes it works now! I think the problem was that my main groups where in fact group items. that’s the only way I used groups. But a member radio in a Dimmer item group doesn’t work. Now my groups are clean and correct (i hope) and now it doesn’t matter in which file I refer to the main groups.

Thanks @hafniumzinc this is very helpful!

One point though I still don’t get (maybe I have not fully understood the semantic model…):

In case my Thing (aka Equipment) does only have 1 Item (aka Point), should I really add a Group Item to represent the Equipment?

Example Light: If I have a physical lightbulb :bulb: which has multiple items (e.g. on/off switch and color wheel) I fully get the idea to represent the physical lightbulb (in addition to the openHAB Thing) also as a Group Item (aka Equipment) - with multiple items (e.g. Switch item, Color item) linked corresponding to semantic Points (e.g. switch type Point and setpoint type Point). But in case the physical lighbulb has only an on/off switch (nothing else) it would mean that by introducing the semantic model, I would not only need to add a tag (in my item file) but also an additional Group Item…

Thanks for shedding some light into this… :blush:

No, you don’t have to. You can add Points directly to Locations if you like.

Got it - thanks! But is there any best practice of how to do this? Eg considering implications for creating widgets etc.? I just want do it right from beginning on as there is quite some (re)work moving to OH3…

I have everything in config files (been using OpenHab since the config files era and like it that way).

I found a difference when it came to how cards were shown under the Location tab depending on the type of definition.

When adding a Point directly to a Location no card is generated but when adding it via an Equipment the card will pop up under “Locations” tab.
(If I remember right defining the point as a Measurement also did the trick as well).

Dear all

I’m beginner with semnatic model

I have a PIr sensor I use for double purpouse:

  1. as alarm if alarm system is active
  2. as presence sensor

I declared a group (equipment) that belong to location gInterno
Group eqPirAlarm "Sensori Pir" (gInterno) ["AlarmSystem"]

and a second one that belong to location gCameraLC

Group eqSensoriCameraLC “Sensori Camera LC” (gCameraLC) [“Sensor”]

and the item

Switch Pir_Camera_LC_Occupancy  "Camera LC Occupancy"  <switch> (eqPirAlarm,eqSensoriCameraLC) ["Status","Presence"]   {channel="mqtt:topic:mosquitto:Pir_Camera_LC:occupancy" } 

but the item is only visible in the second location (gCameraLC) and not also in the first one.

it’s possible to see one item in two location?
How I have to define it?

Thanks for this very good tutorial how to setup this in items file.
I did this for my whole items but struggling a bit to get the correct ones to have them shown up in the “Locations” page.

Especially the windows are not showing up there.
I use:
Group gWindowSensorBedroom "Fenster Schlafzimmer" <window> (Schlafzimmer) ["Sensor"]
as Group.
A window contact item:
Contact DCH_WT_Kontakt "Schlafzimmerfenster [%s]" <contact> (gWindowSensorBedroom) ["Window","OpenState"] { channel="zwave:device:....sensor_door" }

From my point of view there is no specific Window Sensor Equipment.
According to Semantic Model | openHAB it seems to be correct but no window shows up in Location View. I configured to show all badges there (so enabled none specific which should show all).

Any suggestions what’s wrong here?

Hi Joerg, @jh1777
i had the same problem and could solve it.
My window contacts are single channels items of type “Contact”. So for me it should make sense they are points of type “OpenState” with property “Opening”. So I tried:

Contact	EG_WoZ_Fenster	"Wohnzimmerfenster [MAP(de.map):%s]"	<contact>		(EG_WoZ, FensterOffen, FensterOffenUnten) ["OpenState", "Opening"]	{channel="homematic:HM-Sec-SCo:XXX:XXX:1#STATE"}

This showed as assumed the window state at room EG_WoZ as point. But didn’t show the badge!
After changing ["OpenState", "Opening"] to ["Window"] OH showed this item contact as Equipment at the correct room and the Badge was working!

Contact	EG_WoZ_Fenster	"Wohnzimmerfenster [MAP(de.map):%s]"	<contact>		(EG_WoZ, FensterOffen, FensterOffenUnten) ["Window", "OpenState", "Opening"]	{channel="homematic:HM-Sec-SCo:XXX:XXX:1#STATE"}

You see [“Window”, “OpenState”, “Opening”] worked too but I don’t know weather it makes sense, in means that I don’t know wether one item can be equipment and point at the same time.

CAVE: Window badge is only shown when Window is open. It disappears when Window closed!

Thank you @hafniumzinc for the good and important tutorial. As you can see at the multiple other threads in the last months to this issue, that at the end link this post! I think many openHABians want to stay at textual definitions. Its much easier to maintain many hundreds of Items in VScode than clicking.
But, I (have) had a problem that the semantic model was not build correct from files. Took me a long time.

Be careful: Semantic Tags are case sensitive and have Different spelling conventions:


Stripe with upper case is correct vs.


Bulb with upper case is wrong!!! And the items are not parsed to the model.

lower case for bulb is right!!!




Contact DCH_WT_Kontakt “Schlafzimmerfenster [%s]” (gWindowSensorBedroom) [“Window”,“OpenState”]

You tagged the Group as equipment (“Sensor”), which is correct. But the items added to this group must not be tagged as equipment as well. Instead of “Window”, which is an equipment too, you must tag this item as a point with a property.

Thanks together for your answers! All you wrote is correct…

I now removed the Equipment from the Item and changed the group from Sensor to Window - now it works.
Still doesn’t look as nice as in the demo - the icon is hardly identifiable as a Window but is shown when the window is open.

Anyway I would wish to have a more sophisticated and customizable Room Tile to be available out-of-the-box in OH3… Building that on your own is quite some work.

1 Like

Isn’t there a more explicit way to add Equipment to the model? I have a lot of things with only wohne item like a lightbulb with just one switch. It would be great to add the Equipment directly to the Thing definition instead of adding a group which leads to a lot of overhead.

1 Like

Equipment is defined by adding metadata to an Item, not a Thing - there’s no way around this. Note that Equipment doesn’t have to be a Group Item, as stated in the OP, though it usually is one.