Add semantic equipment tag on things #4617

andrewfg · 2025-02-23T11:39:38Z

The purpose of this PR is to add a semantic (equipment) tag to things so that the UI can use that tag for putting items that are bound to channels on such things in the semantic model.

Adds two things:

Extends the XSD schema definition to add a semantic (equipment) tag on thing types. See also Add restrictions for semantic point/property tags on channels #4615
Adds code to permeate this tag throughout OH core wherever it may be needed. Specifically in the classes, DTOs and (de)serializers for thing types and things.

See also #4616 #4619 #4622

Resolves #4614

Signed-off-by: Andrew Fiddian-Green [email protected]

Signed-off-by: Andrew Fiddian-Green <[email protected]>

openhab-bot · 2025-02-23T11:52:22Z

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-5-semantic-model-proposal/162526/96

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg · 2025-02-24T13:38:20Z

@mherwege can I kindly ask you to be a sparring partner for this PR? My goal is to allow developers to set a (proposed) semantic (equipment) tag in their thing type xml, and have this permeated through the thing type instances to the actual thing instances so that the UI can use that semantic (equipment) tag (as a hint) in creating a semantic model.

mherwege · 2025-02-24T15:24:35Z

@mherwege can I kindly ask you to be a sparring partner for this PR? My goal is to allow developers to set a (proposed) semantic (equipment) tag in their thing type xml, and have this permeated through the thing type instances to the actual thing instances so that the UI can use that semantic (equipment) tag (as a hint) in creating a semantic model.

@andrewfg Sure. I like the idea as long as it does not then enforce anything on the item semantics. So I would think that it should be carried to the point of a having a tag on the thing, but then it should be up to the UI to pick this up as a suggested equipment semantic when creating the group item with its points (create model from thing).
As it should not be used on the thing directly, except when creating items, I am wondering what it should be called. Some day someone may think it carries meaning beyond a suggestion for an equipment group item, and may want to also show that in the UI...

andrewfg · 2025-02-24T16:49:15Z

Indeed. The tags in the ChannelType xml are hints for semantic “point” and semantic “property” tags which are intended for functional Item creation. And the single tag in the ThingType xml would be a hint for the semantic “equipment” tag intended for semantic GroupItem creation. The remaining “location” semantic tag is entirely user dependent and would not come from the xml.

PS we could even explicitly name it equipmentTag ..

Signed-off-by: Andrew Fiddian-Green <[email protected]>

...rg.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/builder/ThingBuilder.java

jlaur · 2025-02-25T16:56:10Z

...config.discovery/src/main/java/org/openhab/core/config/discovery/DiscoveryResultBuilder.java

+     * @param semanticEquipmentTag semantic (equipment) tag
+     * @return the updated builder
+     */
+    public DiscoveryResultBuilder withSemanticEquipmentTag(@Nullable String semanticEquipmentTag) {


I'm wondering if it would be better to stay consistent and generic like e.g. here:

openhab-core/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/type/ChannelTypeBuilder.java

Lines 54 to 68 in 6bf5960

/**

* Adds a tag to the ChannelType

*

* @param tag Tag to be added to the ChannelType

* @return this Builder

*/

T withTag(String tag);

/**

* Sets the StateDescription for the ChannelType

*

* @param tags Collection of tags to be added to the ChannelType

* @return this Builder

*/

T withTags(Collection<String> tags);

so simply withTag?

See #4617 (comment) above.

I am fine either way.

@jlaur some background..

In ChannelType we have a tags element that currently allows an unlimited number of tag sub-elements, which have no XSD schema validation. So this allows developers to have an open ended number of strings having open ended meanings.

I think it is the wish of OH maintainers to restrict the number and the meaning of these tags. So there should be a maximum of two tag sub-elements. And strictly speaking one of those tag elements is a semantic point tag and the other is a semantic property tag. And the developer choices when entering such values shall be subject to stricter XSD schema validation in order to restrict the choice to only valid tags.

// as it is today (open ended number and meaning) <tags> <tag>blah</tag> .. <tag>blah</tag> </tags>

In #4615 we are trying to do this constraint and validation. However since the tag elements have the same name we cannot do it fully via the xml. We would need to change the schema to do that (see below) which would be a breaking change. So I am loth to go all the way in doing that. But nevertheless we are moving towards more strictness rather than less.

// as it should be (constrained number and meaning) <tags> <semanticPropertyTag>XSD validated Property</semanticPropertyTag> <semanticPointTag>XSD validated Point</semanticPointTag> </tags>

Now -- finally to get to the point -- as we are moving towards more strictness in the ChannelType tags (semantic property tag resp. semantic point tag), we should NOT be moving to introduce less strictness in ThingType.

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg · 2025-02-28T12:32:23Z

Ok. I have now tested this, and I think it is ready for review. See OH Rest API output below..

http://192.168.1.232:8080/rest/things?summary=true&staticDataOnly=true

[
  {
    "editable": true,
    "label": "Hue motion sensor 1",
    "bridgeUID": "hue:bridge-api2:001788fffe2157c7",
    "UID": "hue:device:001788fffe2157c7:70660557-692d-4d37-8b6b-e3ec63716a72",
    "thingTypeUID": "hue:device",
    "semanticEquipmentTag": "Sensor"
  },
  {
    "editable": true,
    "label": "Contact Sensor",
    "bridgeUID": "hue:bridge-api2:001788fffe2157c7",
    "UID": "hue:device:001788fffe2157c7:faac7940-a303-4e8e-9f06-075fffb7229c",
    "thingTypeUID": "hue:device",
    "semanticEquipmentTag": "AlarmSystem"
  },
  {
    "editable": true,
    "label": "Philips Hue (192.168.1.108)",
    "UID": "hue:bridge-api2:001788fffe2157c7",
    "thingTypeUID": "hue:bridge-api2",
    "semanticEquipmentTag": "NetworkDevice"
  },
  {
    "editable": true,
    "label": "Hue tap dial switch 1",
    "bridgeUID": "hue:bridge-api2:001788fffe2157c7",
    "UID": "hue:device:001788fffe2157c7:ebca68a4-9312-4d3b-86a9-59b5a4a6a988",
    "thingTypeUID": "hue:device",
    "semanticEquipmentTag": "WallSwitch"
  },
  {
    "editable": true,
    "label": "Conservatory Wallplate Switch",
    "bridgeUID": "hue:bridge-api2:001788fffe2157c7",
    "UID": "hue:device:001788fffe2157c7:a0509519-3ecb-47d0-9183-25db1e4ea2b2",
    "thingTypeUID": "hue:device",
    "semanticEquipmentTag": "WallSwitch"
  },
  {
    "editable": true,
    "label": "Office",
    "bridgeUID": "hue:bridge-api2:001788fffe2157c7",
    "UID": "hue:room:001788fffe2157c7:1166743f-fe3d-47d1-bd7d-b5bb378098cc",
    "thingTypeUID": "hue:room",
    "semanticEquipmentTag": "Lightbulb"
  },
  {
    "editable": true,
    "label": "Office Lamp",
    "bridgeUID": "hue:bridge-api2:001788fffe2157c7",
    "UID": "hue:device:001788fffe2157c7:24e7a04e-ad36-4192-961e-ca7f22103cbc",
    "thingTypeUID": "hue:device",
    "semanticEquipmentTag": "Lightbulb"
  }
]

Obviously it needs work now on the OH WebUI side in order to utilise this semanticEquipmentTag when creating the semantic model. => @mherwege :)

Notes:

The actual tag values are still under discussion in Add Airflow, Application, Channel, and Mode Semantic Properties #4616, Add semantic equipment tag on things #4617, Scrub the semantic tags and add missing tags #4619, Create static constants for the default semantic tags #4622 .. but this PR is primarily about implementation in things and DTOs.
Exception: the XSD enumeration restriction in the thing-types.xsd schema will need to be finally updated to match those PRs.

andrewfg · 2025-02-28T12:33:45Z

Ping @jimtng

Signed-off-by: Andrew Fiddian-Green <[email protected]>

bundles/org.openhab.core.thing/schema/thing/thing-description-1.0.0.xsd

Signed-off-by: Andrew Fiddian-Green <[email protected]>

mherwege · 2025-03-04T08:44:13Z

Obviously it needs work now on the OH WebUI side in order to utilise this semanticEquipmentTag when creating the semantic model. => @mherwege :)

I don't think this is a very complex change in the UI. I can take care of it, but would prefer to finish the core code first. There are a lot of moving parts and dependencies here, and creating a core that has it all for testing a UI change against is a bit of a challenge. It will be easier to do when we get the core changes over the line first.

add xsd schema for thing tags

154fc25

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg requested a review from a team as a code owner February 23, 2025 11:39

andrewfg marked this pull request as draft February 23, 2025 11:39

andrewfg mentioned this pull request Feb 23, 2025

Add restrictions for semantic point/property tags on channels #4615

Open

andrewfg changed the title ~~XSD Add new definition for semantic tags on things~~ XSD Add new definition for semantic tags on thing type definitions Feb 23, 2025

add tag field to interfaces, classes, and helpers

1bc1c82

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg changed the title ~~XSD Add new definition for semantic tags on thing type definitions~~ XSD Add semantic tag on things Feb 23, 2025

fix rest module build errors

4872200

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg marked this pull request as ready for review February 23, 2025 16:24

andrewfg marked this pull request as draft February 24, 2025 07:56

andrewfg added 3 commits February 24, 2025 10:59

tweak jaxb

ba8d1ea

Signed-off-by: Andrew Fiddian-Green <[email protected]>

add unit test

d9bdda9

Signed-off-by: Andrew Fiddian-Green <[email protected]>

add tag to factory and builder

376a7a8

Signed-off-by: Andrew Fiddian-Green <[email protected]>

Merge branch 'openhab:main' into tag-xsd-thing

fa02b41

andrewfg mentioned this pull request Feb 24, 2025

Add Airflow, Application, Channel, and Mode Semantic Properties #4616

Open

andrewfg added 4 commits February 25, 2025 10:42

Merge branch 'openhab:main' into tag-xsd-thing

42225da

refactoring

fe8a081

Signed-off-by: Andrew Fiddian-Green <[email protected]>

fix itest

1cc2de4

Signed-off-by: Andrew Fiddian-Green <[email protected]>

simplify xml element

c92ea79

Signed-off-by: Andrew Fiddian-Green <[email protected]>

jlaur reviewed Feb 25, 2025

View reviewed changes

...rg.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/builder/ThingBuilder.java Outdated Show resolved Hide resolved

jlaur reviewed Feb 25, 2025

View reviewed changes

javadoc author tag, fix typos, fix deserializer

56fda66

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg mentioned this pull request Feb 25, 2025

Scrub the semantic tags and add missing tags #4619

Open

andrewfg added 3 commits February 26, 2025 18:57

deserializer tweaks, and unit test

957ff30

Signed-off-by: Andrew Fiddian-Green <[email protected]>

revert discovery; change element name; tweaks

2caca0c

Signed-off-by: Andrew Fiddian-Green <[email protected]>

resolve test failure

4339d5c

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg mentioned this pull request Feb 28, 2025

[hue] Apply semantic equipment tags dynamically on things openhab/openhab-addons#18341

Open

andrewfg marked this pull request as ready for review February 28, 2025 12:32

andrewfg requested review from jlaur and mherwege February 28, 2025 12:32

andrewfg added 2 commits February 28, 2025 14:48

fix bridge builder

9447239

Signed-off-by: Andrew Fiddian-Green <[email protected]>

fix editThing methods

fd607e3

Signed-off-by: Andrew Fiddian-Green <[email protected]>

andrewfg changed the title ~~XSD Add semantic tag on things~~ Add semantic equipment tag on things Feb 28, 2025

javadoc; ignore unchanged file

43d9756

Signed-off-by: Andrew Fiddian-Green <[email protected]>

This was referenced Mar 1, 2025

Generate valid tags in thing-description-1.0.0.xsd #4626

Draft

Add semantic equipment tag on things #4614

Open

Adding "category" property to things #3467

Closed

add markers for openhab#4626

fec5432

Signed-off-by: Andrew Fiddian-Green <[email protected]>

jimtng reviewed Mar 1, 2025

View reviewed changes

bundles/org.openhab.core.thing/schema/thing/thing-description-1.0.0.xsd Outdated Show resolved Hide resolved

revert comment

d3bc5ee

Signed-off-by: Andrew Fiddian-Green <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add semantic equipment tag on things #4617

Add semantic equipment tag on things #4617

andrewfg commented Feb 23, 2025 •

edited

Loading

openhab-bot commented Feb 23, 2025

andrewfg commented Feb 24, 2025

mherwege commented Feb 24, 2025

andrewfg commented Feb 24, 2025 •

edited

Loading

jlaur Feb 25, 2025

andrewfg Feb 25, 2025

mherwege Feb 25, 2025

andrewfg Feb 25, 2025 •

edited

Loading

andrewfg commented Feb 28, 2025 •

edited

Loading

andrewfg commented Feb 28, 2025

mherwege commented Mar 4, 2025

	/**
	* Adds a tag to the ChannelType
	*
	* @param tag Tag to be added to the ChannelType
	* @return this Builder
	*/
	T withTag(String tag);

	/**
	* Sets the StateDescription for the ChannelType
	*
	* @param tags Collection of tags to be added to the ChannelType
	* @return this Builder
	*/
	T withTags(Collection<String> tags);

Add semantic equipment tag on things #4617

Are you sure you want to change the base?

Add semantic equipment tag on things #4617

Conversation

andrewfg commented Feb 23, 2025 • edited Loading

openhab-bot commented Feb 23, 2025

andrewfg commented Feb 24, 2025

mherwege commented Feb 24, 2025

andrewfg commented Feb 24, 2025 • edited Loading

jlaur Feb 25, 2025

Choose a reason for hiding this comment

andrewfg Feb 25, 2025

Choose a reason for hiding this comment

mherwege Feb 25, 2025

Choose a reason for hiding this comment

andrewfg Feb 25, 2025 • edited Loading

Choose a reason for hiding this comment

andrewfg commented Feb 28, 2025 • edited Loading

andrewfg commented Feb 28, 2025

mherwege commented Mar 4, 2025

andrewfg commented Feb 23, 2025 •

edited

Loading

andrewfg commented Feb 24, 2025 •

edited

Loading

andrewfg Feb 25, 2025 •

edited

Loading

andrewfg commented Feb 28, 2025 •

edited

Loading