Best practices/naming conventions for sitemaps, items, etc

Nube here - thanks for the help so far but realize there’s a long way to go. Lotsa reading, lotsa thought expended, head totally swimming.
Read and reread tutorial and documentation, searched forums but have not found definitive answer: What is considered best practices/naming conventions for sitemaps, items, etc. Tutorial uses “default.items” and “default.sitemap”, yet says:

In fact, you can have multiple .items files to sort your items logically, for example lamps.items, contacts.items, network.items etc. As long as the file extension is .items, it’s definitions will be loaded in openHAB. The same applies to .sitemap and .rules files as well

Is “default” the commonly used name? If not, what would be better instead (and why)? For what practical reason would there be multiple .items files? Why have separate .items files for lamps, contacts, etc if they all are in default.items?

First of many upcoming questions, thanks in advance

i try to diffrent them this way

scnTVOn - wil make tv on
siriRoomTV - for siri items
dashTVon - smart dash board items that can have many states
MQTTTVPower - will have the tv power vlaue - for MQTT items
execPCOn - for exec items
infoLocalTemp - for info from all kinds of places

its more easy to search for them , i advice you wait for smart respone as i am noob myself

in OH there optin to create group of items, i just did not get the hang of it…

Welcome Noob :blush:

We all started as noobs , is not a shame.

In some cases, site maps for example, the default value is set to…guess… default.
So if you point to your URL, and don’t specify a sitemap, the system looks for default.sitemap

In other cases, items, rules, Persistance,… the content of the files get load into the internal database, when they get changed. In that cases, dividing in more files is only for the human interaction.

I have my items grouped by the binging, they use. A file for zwave, another for weather, groups and so on. My rules are grouped by thier function : lights, rollershutters, climate control.
That is, what works best for me.

Try, get your experience and find what fits best for you.

Also be aware about naming your items to filter on them…

When you have questions, feel free to ask.

Regards Michael

1 Like

Gad, michael, et al
Thanks for your speedy replies.

So it seems that I just go with default.sitemap, works for me as I see it so far. Would there be any reason to have more than one sitemap? If so, shy?

And I see reasonableness for having separate .items, .rules, etc.

In all the poking around, I came across HomeBuilder. Seems like that just builds the structural framework for one to build upon. But it seems to output only one .items file. Doesn’t seem conducive to dividing by bindings – manually then?

dif site maps can be for diffrent users

like my wife dont need Games,PC etc scnarios …

Great, makes perfect sense! Thanks, Gad

I have the default, with the most common items, for the full control. Then a separated administrative one, where I have more options for setpoints and operating modes. And then I use hab panel for very specified use in more or less fixed rooms.

I built this structure a long time ago. It grew over the years.

If you don’t edit the files “manually” it doesn’t matter. But if you do and you have a few amount of physical items and you start with aliases, lambda and all these geeky stuffs, you will get thousands of lines with items, rules. Have fun to scroll through this files.

Br Michael

Not sure what that means yet. Is that in the documentation? Still cutting teeth on the “easy” stuff.

Will have to think about a separate administrative sitemap, sounds both intriguing and useful. So much to digest.

Dont worry. You’ll find yourself in these topics sooner or later :slight_smile:

What I want to say, the more complex your setup gets, the more items you will have…

This topic comes up a few times a year. The best high level advice is to do what makes sense to you.

Use meaningful names. If you create an admin sitemap, name it admin.sitemap.

They all are not in default.items. Items can only be defined in one place. What you want to do is split up your definitions into separate files so you don’t end up with one massive file with hundreds or thousands of lines of Items. It is a lot easier to find and edit Items across several little files, especially if you split them up in a meaningful way.

Unlike michael, I recommend splitting up .items files and .rules files by function and splitting .things files (if not using PaperUI) by binding. Why?

  • Items represent the model of your home automation. It shouldn’t matter what technology the family room lamp uses to turn on and off, just that you have a switch to control it.

  • You may find you end up with a mixture of technologies for the same tasks. For example, I have both zwave and sonoff to control my lighting. It is much more intuitive to find if they are defined in the same file, plus, we shouldn’t have to care what the technology is. Put all the lighting Items together in a lighting.items file and you will know instantly where to find the Item that represents the family room lamp without some mental map that requires you to remember that the family room lamp is controlled via zwave.

  • A significant percent of your Items will be Unbound Items. Where do these Items that are not bound to or linked to anything go? If you put all your items together by their function, then these unbound Items which often represent settings (e.g. HVAC target temperature) will be co-located with the Items they help to control.

  • It provides a nice pairing between the .items files and .rules files. If you, for example, put all your lighting Items in a lighting.items file and all your lighting Rules in a lighting.rules then for the most part all the Items that are used in lighting.rules will be found in lighting.items.

  • For rules, if you separate them by function then you will be better able to take advantage of shared resources like Timers, lambdas, and global variables. These can only be used by Rules defined in the same file.

Anyway, I wholly agree and suggest you do what makes sense for you. You are the one who has to build this up and use it.

Hey Rich

I guess there is no overall “wrong” or “right” regarding the naming. My described solution works best for me, because:
When I do a change on the binding, I have all my items in one file, so I can’t forget any item, which lays in a rarly touched file :slight_smile:
But I can follow your arguments to. I’ll gonna try it the next time, I build a solution from the scratch.

I have also a file, which is called virtual.items :slight_smile:


Theoretically, all of that should be encapsulated in Things, not Items. And I do recommend splitting the .things files by binding. Though if you are still using a lot of OH 1.x bindings that won’t be the case.

Indeed though, there is no right or wrong. Use an approach for what works. I just wanted to provide an alternative and why I prefer it and recommend it.

Hi, Rich

This topic comes up a few times a year. The best high level advice is to do what makes sense to you.

Precisely what I was searching for, though I’m blind or oblivious cuz I just couldn’t find any of 'em. I appreciate your reasoning, makes great sense. How could I separate things files? Possible with PaperUI? Or???


There is no need to separate anything in PaperUI since it puts everything together in the UI anyway. But a lot of users, especially old timers, like to define everything using text files. I mostly use PaperUI to manage Things and define Items Rules and Sitemaps in text files.