OH 4.0: Tutorial to manage custom semantic tags

In openHAB 4.0, some technical refactoring in the core framework were done to define a registry for semantics tags and define a REST API to manage semantic tags (add/remove/update). The default semantic tags cannot be changed but you can add new equipment, new location, new property and new point as you wish.

Unfortunately, OH 4.0 was released without a new page in Main UI to manage semantic tags and without support of a new configuration file providing semantic tags. This can certainly be expected for openHAB 4.1.

For the configuration file option, my proposal is already submitted and discussed but it was decided to delay the merge after release of OH 4.0.

To enable this feature, you first need to install a new bundle. Simply download the following file, change its extension to .jar and place it in your addons folder.
org.openhab.core.model.yaml-4.0.0.pdf (18.4 KB)

Then create a “tags” subfolder in your conf folder.

It was decided to rely on a YAML format for the configuration file. So, for example, create a file named myTags.yaml (the yaml extension is important) and place it in the “tags” folder to trigger the loading of its content.

If you have basic knowledge of YAML, the specific syntax for defining a semantic tag is very simple. Here is an example file:

# Configuration file containing a list of custom semantic tags

version: 1

# For each semantic tag:
#  - uid and label are required
#  - description and synonyms are optional


  # Example of a new equipment
  - uid: Equipment_Curtain
    label: Curtain

  # Example of a new location
  - uid: Location_Indoor_Room_HomeCinemaRoom
    label: Home Cinema Room
    description: The room containing my home cinema system.
      - Home theater room
      - TV room
      - Movie room

The “uid” is very important and define the location of your semantic tag in the tree. In the example, “Location_Indoor_Room_HomeCinemaRoom” defines semantic tag “HomeCinemaRoom” as child of “Room” which is itself child of “Indoor” which is itself child of “Location”. There are constraints on the name of a semantic tag (like HomeCinemaRoom); it must start with a capital letter letter and contain only letters and numbers.

You can have multiple YAML files with different semantic tags but keep semantic tags dependent on each other in the same file.

Now reopen Main UI (semantic tags are loaded by Main UI when you open Main UI).
Create a new group and select HomeCinemaRoom as semantic tag:

Create a new group and select Curtain as semantic tag and “My Home Cinema Room” as parent group:

Now, go to the Equipment tab in Main UI and you will see:

Now, go to the Location tab in Main UI and you will see:



Please, note that custom defined tags (myTags.yaml file) seems to be loaded after .items definition files.
New tags are taken in account only after .items files loading (thus seem unknown in the model view until the item file is reloaded). I observed the same behaviour when items are GUI defined (but then you can not force reload them).