Semantic Model - Best Practices


I am going to upgrade from 2.5 and thinking how to define the Semantic Model --> what is the “right”/best way to do it.

For example, I have a room with 6 Things:
• Shelly2.5 Model1 – Light1.1, Ligh1.2, Alarm1
• Shelly2.5 Model2 – Light2.1, Light2.2, Alarm2
• Shelly2.5 Model3 – Bind1, Alarm3
• Shelly2.5 Model4 – Bind2, Alarm4
• Thermostat – ThermTemperature, Battery
• HVCA – Mode, HVCATtemperature, Setpoint

Should I define an Equipment for each Thing?


Should I define an Equipment for each “family” of Things:


Should it be more general:


1 Like

I think there is probably no definitive answer to your question as the ontology allows for various configuration.

I would point out that you have broken the ontology in your examples 2 and 3. I would suggest that Room(Equipment) is not a good idea and is just creating a redundant node anyway.

I think you would find that you can put the points directly under the parent room(location) and the result would be fine if that is how you like things to work,

Thanks, good to know that I can put the points directly under the parent room(location)

I would be happy to continue this as a conversation as it is interesting to see how others are using the model.

For light switches and dimmers where there are multiple in a room, I have been using the wall switch equipment to group them. For switches this gives you an all off switch the way I have done it. I am not sure if this should also behave as an all on switch. I am not clear if this is as designed, a missed option in the configuration or a bug so working with others would be good.

There is no real right and wrong in setting up the model so long as you stick to the rules (e.g. locations are Groups, can’t have an Item in more than one semantic Group, etc).

Having said that I can say how I think about it and implement it.

  • Forget about Things and thing about the “real world.” If you can point at a box and say “that’s a ‘Foo’”, you’ve just identified a piece of equipment. Why is this important? Because Foo might actually have Points that come from different Things and even different bindings. For example, if it’s a network device, you can have an online status Point linked to the Network Binding while the rest come from the MQTT binding, for example.

  • It also might make sense to split a Thing up into separate Equipment or points. For example, I have a temp/humidity sensor that reports over MQTT and a Zigbee smart plug that controls a simple humidifier. I could model them as two separate pieces of equipment but that doesn’t really make sense. Instead I take the Switch from the smart plug and the humidity reading from the sensor and put them into a new Humidifier equipment. The temp is just a Point under the room where it is. The power usage and other Channels from the plug I leave out of the model.

  • Don’t over think it. The model represents what you are trying to build from a human perspective. It’s there to help you, not lock you into a way of thinking about it.


I have a similar issue getting up and running with the OH3 and the LCN system in my rental apartment. The way this LCN system works, one disovered module “thing” will have dozens of channels for relays, dimmers, shutter controls, sensors, etc, that control devices in different rooms. Any given room may have lights, shutters, sensors from multiple module “things.”

In my various attempts to build a semantic model that makes sense, I tried just adding individual channels as points to rooms, but points that aren’t under equipment don’t show up in the Locations or Equipment tabs in the UI. So If I want to setup the semantic model in the way that makes the most sense to me, I have to do more work making the devices accessible. Is that reasonable or expected? Am I missing something obvious?


Are you sure? They should be there in the location tab as well as in the properties tab. If they are missing there is something wrong. Can you show the config…

For equipment tab it is OK. When there is no equipment defined of course there is nothing to show under equipment.

I’m sure. When I get home from work this evening I’ll build a small semantic model that way again (I’m creating and tearing down repeatedly anyway as I try to find my sweet spot) and post the config.

I checked it and saw that when a channel is defined directly under a Location you can see it in the Location card under the Properties tab:


For me, when I created locations that contain only points (no equipment), nothing at all was populated on the location or equipment tabs in the home page of the UI.

That might be worth an issue. It should show the Properties even if there isn’t an equipment. However, do you have Property Tags on these Points, or just the Point? For example, a light switch I would expect to have a “Switch” Point tag and “Light” as the Property tag. If you are lacking that “Light” tag then the Point isn’t a Property so won’t be shown.

Thanks. That was it. When I added a point from a thing (a specific channel on an LCN module) it didn’t populate property so it didn’t show up in the location. Still trying to get my head around all the basics.

That said, what property would you set for a rollershutter? Opening?

Probably. Ultimately it comes down to what makes the most sense to you and to be consistent.

Hey there, joining in the conversation-
I started experimenting with a new installation of OH3 and checking all the amazing upgrades, including the semantic model.

I noticed that some definitions has special characteristics that i couldn’t see in the documentation and I’m wondering what other characteristics i might be missing.

For instance, i noticed that if a point defined as class measurement, OH starts to log the value (assuming using rrdj4?) and in the cards view i can see the historical data.

Is there a documentation i missed that describes all the different behavior of the different classes and properties?
What’s the difference between a ‘switch’ class and ‘control’? ‘Status’ vs ‘Alarm’?
Other than just what makes sense to me…


Not yet. The UI tries to make a best guess on how to represent an Item based on the Item type. I didn’t think it used the model yet to make that guess so I’m surprised changing the tag is what started the generation of the chart (the data is already saved for all Items by default).

When OH gets it wrong, you can override the widgets that are shown by editing the default widget metadata on the Item.

I think Alarm will be shown as an icon on the top level card on the auto generated tabs of the overview page.

A switch would typically be binary and a control would have more than just ON and OFF. For example, the player Item for a Chromecast I would tag with control.

@rlkoshak thank you for the explanation.

Is it using the default persistance method i chose at the settings? Is it configurable in files like OH2.5?

Exactly the kind of insights I was looking for. Is there a wiki page (even if in progress) that give these kinds of details?

And in the case where I’m creating my own pages and not using the auto generated ones, is there any other meaning to the semantic tags? Do they play a role behind the scenes in other places?


Just found the wiki page you started to write @rlkoshak about building pages…
Got my answer :laughing:


They are used by HABot. You can access tags and access all the Items with a given tags from Rules so you could take advantage of the model there.

Thank you very much!
Will continue to play with my new OH3…
Looks very interesting so far!

Hello all, I would like to add to the conversation, too. I’m also setting up OH3 from a clean installation with a PI4 in stead of continuing my fight to keep my 2.5 Synology installation going… This way I also get the chance to setup the model from scratch and I’m really struggling about one thing. I chose for a config that looks like “option 1” from TS the most. starting of with a “outside” and a “inside” on the top level of my model. As it turns out I have a smart switch that is inside my house (lvl2), in my living room (lvl3), which is controlling my garden lights that are (knowlegde bomb, watch for it) outside.

so, am I going to go for an equipment located outside that is my lights, containing a thing that is my switch which is now not visible as part of my living room, or am I creating a equipment that is a switch, located in my living room…