A Deep Dive into the Semantic Model

There continues to be a steady stream of posts for help about the semantic model, how to use it, best practices, etc. One common problem is an assumption that the model does more than it really can right now. Another problem is the assumption that the model has to be used.

This tutorial is going to be a deepish dive into the semantic model, much deeper than is suitable for the Getting Started Tutorial. I’m also going to present my suggested best practices. I’ll try to identify those as my suggestions are not the only way to work with the model and may not be the best approach in all cases.


Believe it or not, the semantic model was first introduced way back in OH 2.4.0 M5. It was originally introduced to provide more meaning to Items than the standard Item definitions can provide. The reason for adding this new layer on top of Items was to support a natural language interaction between openHAB and a then new (still maintained and available) user interface, HABot.

In order to support interactions like “Turn on the lights in the master bedroom”, HABot needs to know which Items are in the master bedroom and which of those Items control the lights.

How the Semantic Model is Implemented

As already mentioned, the semantic model is a layer built on top of existing Items structures and features, namely Item tags, Group membership, and Item metadata.

Item Tags

These provide information about what a given Item represents semantically. The tags were initially adopted from the Brick Schema but have had additions and changes made for use in openHAB.

There are four categories of tags. Any given Item can only have one tag from one of the following categories.


A Location tag is applied to an Item that represents a location. A location can be very broad like “Indoors” or very specific like “kitchen”. These Items don’t actually do anything. Their entire purpose is to represent the physical layout of your home automation system.


Commonly, one device will have multiple actuators (i.e. controls, things that can be commanded to cause an action to occur) and/or sensors. Despite this, the device is a single unit, often represented in openHAB as a single Thing. Therefore , equipment tags are applied to Items that represent a device, like a multi-sensor, HVAC system, etc.

Often an equipment will have a one-to-one relationship with a Thing. However, it is reasonable and expected that multiple Things even from multiple different bindings might be combined in a single equipment. For example, one might have a Zwave smart switch connected to a dumb humidifier combined with an MQTT humidity sensor and an Unbound Item combined into a single humidifier Item tagged with the “HVAC” equipment tag.


A point tag applies to the Item that represents the actual actuator or sensor such as an individual Switch for an actuator or a Number:Temperature for a sensor. The point tag indicates what the Item does.

What does that even mean, “what the Item does”? Let’s look at some examples. A thermometer might use a “Measurement” point tag because it represents the measurement of something. A light switch might use “Switch” as the point tag since it switches something on or off. A Play Item to control a media player might use a “Control” tag. An Item that switches ON when the smoke alarm detects smoke might use an “Alarm” tag.

One might ask, how do I know that the Number:Temperature Item is a “Measurement” of temperature? That’s where the properties tag comes in.


A properties tag can not exist without a corresponding point tag. They never apply to the same Item tagged with an equipment or location tag.

Point tags indicate what the Item does. To indicate that our Number:Temperature Item is a “Measurement” of temperature, we’d add the “Temperature” properties tag. That smoke alarm would use the “Smoke” properties tag. A humidity sensor might use “Measurement” as the point tag and “Humidity” as the properties tag. As a short hand I’ll indicate a point properties tag pair using “/”, e.g. “Measurement/Humidity”. That switch that turns on the humidifier might use “Switch/Humidity”. A water leak alarm might use “Alarm/Water”.

Hopefully you can see how rich the opportunities are to build the model using just these two tags.

Group Membership

In addition to just identifying what each Item represents using tags, the semantic model supports the creation of a hierarchy. The hierarchy represents the physical layout of the home automation (i.e. what is in what location) and the groupings of individual Items into equipment.

The actual hierarchy is created through Group membership. An Item with a point tag becomes a part of an equipment by making it a member of the Group Item with the equipment tag. A point or equipment is placed in a given location by making it a member of the Group Item tagged with that location’s tag.

There are some rules about these Group memberships though.

  • Any given Item can only have a tag from a single category of tags above with the exception of properties which can only be tagged on an Item that already has a point tag.

  • Location Items can only be Groups.

  • Locations can have any number of other locations, equipment, or point tagged Items as direct members.

  • Equipment Items can be Groups (the usual case) or single Items (not recommended, see below).

  • Equipment can have any number of points or equipment tagged Items as members.

  • Point Items can be Groups (rare use case) or single Items. If a Group, the members of the Group should not have any semantic tags and the Group should have a type and aggregation function.

  • No semantically tagged Item can be the direct member of more than one semantically tagged Group.

  • Any semantically tagged Item can be the direct member of any number of non-semantically tagged Groups.

Let’s look at an example hierarchy, a humidifier I have in my front room.

At the top of the hierarchy I have a location “Wuthering Heights”. That represents my home. You’ll also notice I have another root location, my “Dad’s House”.

Next I’ve split the location hierarchy into floors. There are three floors in my house including the basement and I’ve three Group Items tagged with the appropriate tag for the floor as a direct member of “Wuthering Heights”.

In the “Ground Floor” I’ve a number of rooms with stuff automated in them and each gets it’s own location Group Item using the appropriate location tag. The humidifier is in the “Front Room”.

Under the “Front Room” there are a number of equipment. Each is represented using a Group Item using an appropriate tag. The closest tag I had to choose from for the humidifier was “HVAC” so that’s what I chose.

Under “Main Floor Humidifier” there are three Items which represent the actuators and sensors that make up the equipment. Each has a different point tag indicating what the Item does but the property is “Humidity” for all of them because all three work with humidity.

Item Metadata

If you don’t use HABot, you can skip this section.

Sometimes one might have more than one name for the same thing. For example, we interchangeably use “front room” and “living room” in our common speech in our house. Given that HABot is supposed to be based on natural language it needs to be able to support that. It does so by offering a synonymns Item metadata. You can add a comma separated list of alternative names for the Item (in addition to the label) that can be used to refer to the Item,

How Do I Build the Model?

The previous section should have given you an idea on the mechanics for how to define your semantic model. But it doesn’t tell you how to actually construct the model. Unfortunately that’s not something that a tutorial will be able to address fully. We can’t create the model for you because each and every person’s home automation is unique and the purpose of the model is to help serve you, not impose upon you.

But there is some general advice I can offer.

  • Don’t over think it. Make the model serve you. If it seems tedious or not helpful, you are probably trying to over define/design the model.

  • Not everything needs to be in the model. In my experience about 60% of Items belong in the model. YMMV. In general, if your end users don’t care about the Item it probably doesn’t belong in the model.

  • Approach the model from your home automation user’s perspective. Let’s say you have a smart switch in the hallway that controls a light in the kitchen. The users of your home automation don’t care that the switch is in the hallway, they just want to turn on the kitchen light. So put the switch in the kitchen. The model should represent your home as the users see it and will use it through openHAB, not how you, the administrator, sees it. Specific technologies used, hidden relays in a closet somewhere, and stuff like that are irrelevant to the end users, so don’t model those.

  • You don’t have to use the model if you don’t want to. If you are coming from OH 2 or older you may have no use for the model. Even if you are just starting with OH 3 you may not have a use for the model. So don’t feel compelled to use it. It’s not required.

  • In my opinion, it’s not worth the effort to make the model work in .items files. I therefore recommend that if you do plan on using the model, consider using managed Items instead. If you do choose to use .items files, do not mix and match. There is a bug when some Items are in .items files and others are managed which breaks the model.

  • In my opinion, it’s not worth the effort to retrofit a bunch of existing Items to work with the model. It’s tedious, error prone, and time consuming. Instead, I recommend recreating your Items using the “Create Equipment from Thing” and “Create Points from Thing” options. This will allow you to define dozens of Items all at once in a matter of minutes and the Items will already be situated into the model. Having done it both ways recreating the Items in this way took almost half the time.

  • Be consistent. You want all your lights to work and look the same so model them all the same way using the same tags. For example, I made the mistake of using the “Smart Assistant” equipment tag for my Google Hubs and the “Speaker” equipment tag for the Google Home Minis. This seems reasonable because that’s what they are. However, that ends up splitting them apart in the Overview Pages for no good reason. As another example, let’s say most of my lights are smart bulbs with one that’s just a Switch. Because I can make that single Switch be an Equipment with the Lightbulb tag but the Color Items all have two Items (one for Color and another for Color Temperature) I used a Group with the Lightbulb tag. As a result this odd lightbulb not only gets shown differently on the Locations tab of the UI, it has its own card which is undesirable.

How the Semantic Model Is Used

There currently are four places where the semantic model is used in OH as of this writing.

Model View

The semantic model is how the Model settings page is rendered. The Group membership hierarchy is rendered as a collapsible tree structure making navigating the model quick and visual. The locations, equipment, and point tagged Items are rendered with a different icon (see screenshot above).


There are a collection of new Actions that can be called from rules. These let one determine whether the Item is a location, equipment, or point, determine the equipment or location the Item belongs to, and query for the Item’s tags.

See Actions | openHAB


Ans briefly mentioned, the semantic model was originally developed to be used with HABot. HABot is a UI add-on that allows for a dynamic and free flowing interaction with OH using natural language.

See HABot - UIs | openHAB for details.

Overview Page in MainUI

MainUI is the main UI openHAB users will interact with. Among the administration parts, MainUI presents an Overview Page that consists of four tabs.


This is the first tab and it is what all users will see when first logging into OH. This tab is a Layout Page and should be custom built by you.


This page is populated based on the semantic model. Every location that has a direct member that is an equipment or a point will have a card generated.

Badges may appear on the card based on the states of the point Items that are direct members of that location Group or members of an equipment that is a direct member of the location. For example:

The above screen shot shows the Master Bedroom location. The card indicates that the Master Bedroom location is itself in the Top Floor location. And there are a number of badges that indicated what’s going in in that room. One light is on (there’s a little number if there is more than one). The HVAC is on (in my case the humidifier). The temperature is around 65 °F and the humidity is 36% and the light level is 47.

Identifying which Items represent the lights, HVAC, temperature, humidity and light level is achieved through the equipment, point, and property tags.

One reason to be consistent is so, for example, all the lights appear on the card the same way. If one were to tag a plain old Switch Item with a Lightbulb equipment tag, but the rest are in equipment Groups because they have more than one Item, the Switch will appear on a completely different tab. So either always use an equipment Group or never use one for all the Items of a certain semantic type.

Opening the card will show the individual point Items. If there are any point Items that are direct members of the location and not members of an equipment will be shown on a separate properties tab of the card. The above shows only equipment. Each equipment gets a gray label and the point Items that are a part of the equipment show up below that label. If an equipment has subequipment, that will appear as a row you can click on to open another card showing the points.


This tab works very much like the locations tab with the following differences:

  • Each type of equipment (i.e. each unique equipment tag) gets it’s own card. This is one reason to be sparing in your use of equipment tags. For example:

This is the first row of my Equipment tab. It makes no sense that each door ends up in its own card. They are all doors so they should be grouped together. But I tried to use the most specific equipment tag and there is a separate tag for each type of door. As a result I end up with an Equipment tab that doesn’t make sense. Instead my plan is to change the equipment to just be “door” so they all group into the same card. The same happened when I used different equipment tags for my Home Hubs and Home Minis.

  • Clicking on a card will show each instance of that equipment type similar to how they are displayed in the locations cards.

  • Equipment cards do not show badges.


Notice the name here. It’s “Properties”, not “Points”. Only those point tagged Items that also have a property tag will be represented. Each property tag gets it’s own card and all the Items with that property are displayed, grouped based on the point tag used.

Rules of Thumb and General Advice

  • Always use Group Items for equipment, even if there’s only the one Item.
  • Only include in the model those Items your end users will interact with.
  • Use descriptive labels. Take the screen shot above of the Humidity card. If all the Items are labeled just “Humidity” the card would be completely useless. We couldn’t tell which room the sensor is reporting for.
  • Focus on how things appear to your end users. If a switch controls the kitchen lights, put the switch in the kitchen even if it’s located in another room. Your users don’t care where the switch is, they only care about where the lights are.

Thank you for practical tutorial about semantic model!

One thing I have noticed while trying to set up a semantic model is that it seems to destroy the existing Basic UI :frowning:

My items are generated automatically in Basic UI using Group items in .sitemap file. For instance, I have Group item=GF_Kichen in .sitemap file which allows to see in Basic UI all items attached to this group (after one click) as defined in .items file.

Now when I want to add a “virtual” Group Item in order to define Equipment for the semantic model it results in additional grouping in Basic UI. Assuming I have an equipment (additional Group Item) defined for each item (as recommended) in my Kitchen, this make the Basic UI a nuisance. While clicking on Kitchen I cannot see/change states of item (lamp switch for instance) I need to click on a group in the kitchen first, then switch a lamp.

A workaround to such a behavior might be to define fixed sitemap without Group Items features.

Hence my conclusion that in order to use semantic model and Basic UI in parallel the last one shall be rebuilt.

Frankly, since the beginning, using Groups to build BasicUI was a nuisance and most people abandoned that pretty soon. It’s almost always recommended to build the sitemap without using Groups so you have the control you need over order, widget, and appearance used. All it takes is one Switch Item where you don’t want to show the toggle control (e.g. from the Network binding) to force you down the path of defining everything instead of using Group elements.

Since, for now, the semantic model is primarily a MainUI thing, if you are happy with BasicUI you probably won’t get much benefit from using the semantic model. If you do use the semantic model, the Overview page in MainUI is probably going to be a better option for you to use instead of BasicUI.

A very usefull feature of Basic UI is the possibility to derive and present the group state from members items.
For instance when I see “1” for gWindow Group [Group:Switch:OR(ON, OFF)] I know there is something wrong and after clicking on this group I can see which window is not closed.
My understanding is that despite assigning all windows to the Window type of the Equipment in semantic model, it will not present such type of info (a badge indicating if and how many windows are opened) on the Window-Equipment card?
Is there another way to achieve the same functionality?

1 Like

Thank you, Rich, for your detailed write up. One main cause which kept me from moving over from OH2 was I had no idea how to properly use the semantic model. Did not want to trade my working OH instance for something possibly configured wrong.

But with your article, I’m not only sure I cannot break anything, I feel like having enough understanding to start with the semantic model. Great work.

For instance when I see “1” for gWindow Group [Group:Switch:OR(ON, OFF)] I know there is something wrong

You can still use Groups and their aggregation. That’s independent of the semantic model

My understanding is that despite assigning all windows to the Window type of the Equipment in semantic model, it will not present such type of info (a badge indicating if and how many windows are opened) on the Window-Equipment card?

Yes, if you want to use the semantic model and leverage automatically created ui elements (which are base on the semantic model), than you have to configure the semantic model.
If you do not want to configure the model, you cannot use it.

Do you mean that if I define a semantic model I can see a number of opened windows on Window-Equipment card? It seems to be in opposite to the above:

" * Equipment cards do not show badges. "

Not on the equipment cards, but in the location card, that you can see e.g. open windows by room in one view

Thanks to @rlkoshak for this nice and useful explanation.

A few weeks ago i took the time to build up my own semantic model for my new house.
I also tried my best to place synonyms (mainly on equipment-level bundeling the items as Points)

The main-focus for me is to be able to use the power of HABot in the future.
Im loving the fact, that a well built model may be uses better and better throughout time by increasing progress developing HABot.

Now, playing around a bit i found out that some (in my thoughts) easy commands are not well interpretated by HABot and im wondering if i made mistakes building up my model, misconfigured something, if this may be language-related or if this is just the current state of HABot.

Im using HABot with german language and therefor built up my Semantic model in German Language
Therefor my offices are named something like “Büro NAME”

  • It does not work to write down (in german) "Turn off lights in Büro NAME → HABot turns off all lights in my whole model, or tells me it found nothing → NOT what i wanted
  • It works if i write down (in german) “Turn off lights in Schlafzimmer” → HABot turns off only the lights in the bedroom → OK

→ Is there anyone experiencing the same thing? Is it maybe related to ÖÜÄ?
→ Is there a way to debug how/what HABot is doing and to find out if the error is on my side?

In Case my model is not well built, the structure below


I’m not really using HABot for a whole lot lately. So I don’t know if I can help much. You might open a new thread to discuss it. I don’t think there has been any changes to HABot in quite some time and I remember having some odd behaviors like this. I think it looks at the labels first and if it finds a close enough match it uses that. Only if it doesn’t find a match does it check the synonyms.

1 Like

Hi Rich,

Thank you for this helpful article.

I managed to do a radio group with the following sitemap:

sitemap modbus_ventilation label=“Ventilation Unit” {
Frame {
Selection item=VentilationButton label=“Ventilation Unit” mappings=[ “1000”=“Level 4”, “0”=“Level 3”, “2000”=“Level 2”, “3000”=“Level 1”, “4000”=“Off”, “5000”=“HR Level 1”, “6000”=“HR Level 2”, “7000”=“HR Level 3”, “8000”=“HR Level 4” ]

And I need some information on how to recreate it on the semantic model.

Kind regards,

In short, you don’t. The semantic model doesn’t control that. You’ll need to set state description metadata on the Item and/or use a custom “default list item widget”. I think if you set the widget to be an input widget and set the mappings in the options section of the state description metadata you’ll get a list where you can select each option.

If you want buttons, look in the marketplace for multi-button widgets you can use or learn from and customize.

1 Like

Thank you Rich, it works :slight_smile:
I set the options for the stateDescription and added a default list item widget with the widget set as ‘label list item’. In addition to that I configured also the action as ‘command action’ with the action item pointing to my device.
Kind regards