Best way to format item files?

Besides all discussion about Ui driven or file based configuration one of my problem is how to keep things readable.

Rule and Sitemap files are more or less easy to format, but how to format an items file with all its possible parameters like label, icon, channel, … so that is is easy readable.

What is your best practice on that?


Use tabs to format a single item line (if needed use a small font so you can have a long line) so
it looks like entries to a table.
Use different files one for each technology and/or purpose (such as zwave, max, hue or hvac, presence etc.) and within those files, group items by location. Or vice versa.
Be generous in using empty lines and comments.

As with most questions like these, it depends on what you want to optimize.

For example, if you like to use grep a lot to find Items in your files, it might be worth putting everything on one line. If you find yourself reviewing your files on a small screen like a phone, splitting them up into multiple lines might make more sense.

For me, I find myself needing to look up something I’ve done when answering forum questions and do so from my phone. So I split my Items into three lines:

ItemType Name "Label"
    (groups) [ tags ]
    { binding/channel links }

If it were not for the small screen problem, I would put everything on one line so when I grep I get the full Item definition.

As Markus suggests, using tabs or spaces to get everything to line up greatly helps the human eye see the different parts of the Item. Though this is less important if you use multi-line Item definitions. I don’t necessarily do this strictly though. If you have the file separated into sections, I’d only make the Items in one section line up rather than trying to get the whole file to line up.

I strongly recommend using one file per purpose. This will put Items that are most likely to be in the same Groups and be operated in the same ways in the same place. Inside the file you can organize it in other ways depending on what makes sense, like by room, by floor, or by technology. What ever makes sense to you.

When I do have my .items files organized in a certain way (sometimes there are not enough Items to make sense, or it doesn’t add anything) I’ll insert visual landmarks. Something like

// Sonoff

With white space before it.

I put the definition of Groups as close to the Items that they contain as possible. This isn’t always possible or they address almost all of OH. Thus, if a Group contains, for example, all the SonOff switches, I’ll put the Group definition right under the Sonoff landmark above. If I have a Group for all lighting, I’ll put the Group at the top of the lights.items file. If it is a Group or Item that applies across all of OH (e.g. a notification Item or persistence Group) I have a special “other.items” file where I put those.

Finally, it helps to use the same sort of file and file naming scheme for Items as you do for your Rules. So you will know that lights.items will have Rules that work with them in lights.rules.

As with all advice like this, the primary concern is to be consistent and do what makes sense to you. You’re the one that has to live with these files. :wink:


Originally, I put everything on one line. And, like @mstormi, I used tabs to line everything up. Unfortunately, as I added more and more groups, tags, etc., the length of the line got unwieldy, so much so that I was constantly scrolling up/down/left/right to view my items.

So, I switched to a format like this. Now I just to scroll up/down (albeit a lot more up/down than before), which is a more natural scrolling motion for me compared to left/right.

Switch                      BasementDoor_Lock
                            "Basement Door Lock [%s]"
                            { channel="zwave:device:zstick:node94:lock_door", synonyms="Basement Door" }

Contact                     BasementDoor_Sensor
                            "Basement Door Status [%s]"
                            { channel="zwave:device:zstick:node94:sensor_door" }

Number:Temperature          GuestBR_Temperature
                            "Guest Bedroom Temperature [%.1f °F]"
                            { channel="zwave:device:zstick:node43:sensor_temperature" }

I also wrote a little VS Code extension to make it easy to reformat a single-line item definition into the multi-line format. Whenever I work on an existing items file, it’s easy to reformat all the items.

To create new items, my VS Code extension also has keyboard shortcuts to create the basic item information for several item types I use frequently.

So, for example, on my Mac, Command-i Command-s creates a Switch item that looks like this. Then I just fill in the rest.

Switch                      _Switch
                            "Label [%s]"
                            { channel="" }

Command-i Command-d creates a Dimmer item like this. And so forth for the other items types…

Dimmer                      _Dimmer
                            "Label [%s]"
                            { channel="" }

That is so cool. :ok_hand::clap:

1 Like

Would you be able to share this for use who have loooonnnnng item definitions


1 Like

Yes Please

1 Like

@vzorglub @allen Here you go. Download the latest .vsix and install in VS Code. I just added a (really) brief README.

Let me know if you run into any issues. It’s only been used on my system and with my items. I think the reformatter’s pattern matcher should catch all variations of item definitions, but there may be an edge case that I missed.

It only reformats one line at a time. I haven’t gotten around to making it work on a selection and/or the entire file. In fact, I may never get around to doing that… LOL


Great, Thanks a lot. Installed it, loved it, Filled an issue, because reformating is mot working on indented lines, but anyhow it is great

Thanks a lot


I responded to your issue with a question.

1 Like

Hey Mark,

can you tell me how i can install it on my mac? I’m not sure if i have to install visual studio or visual studio code. It will be great if it works on my mac. thank you very much!


I use it on my Mac all the time.

First you need to install Visual Studio Code. Then use the “Install From VSIX” menu item to install the openhab-formatter-0.0.5.vsix file.

I’d also recommend you install and use the openHAB vscode extension found here.

That is what i have done. After that i also installed extension VSIX. Then i installed via right click openhab-formatter-0.0.5.vsix file. This is the log from it:

Dennis-Mac:openhab-formatter dennis$ code --install-extension “/Users/dennis/Desktop/openhab-formatter/openhab-formatter-0.0.5.vsix”
bash: code: command not found
Dennis-Mac:openhab-formatter dennis$ echo ‘Installation ended’
Installation ended

Is this correct? After that, how can i use this extension?

Sorry for this kind of beginners questions :slight_smile:


Okay, that was my mistake. I found the problem with the missing command.

Ok. I was just about to suggest you check that PATH contains the directory containing code. :wink:

But if i start without debugging i get the following errors:

Cannot find module ‘vscode’. ts(2307) [1, 25]
Parameter ‘builder’ implicitly has an ‘any’ type. ts(7006) [241, 10]

can i fix that problem?


I’m sorry, but I have no idea what that error means. Do you get this when you start VS Code?

A restart brought the solution for these two errors. But now I get the following error:

Errors exist after running preLaunchTask ‘npm: watch’.

Sorry, I don’t know what that means either.