Semantic Tags: developer information/rules

[andrewfg]

This PR improves the documentation for Semantic Tags in two respects:

1. Rules governing how developers/reviewers shall use the set of OH Core semantic tags in addon development.
2. Rules governing how developers/reviewers shall extend (or prune) the set of OH Core semantic tags.

The purpose is to have a clear set of rules for Semantic Tags as the fundamental basis for judging a number of current open PRs that aim to refine/improve/extend the current Semantic Tags functionality.

Follows on from the the discussion in openhab/openhab-core#4619

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

[openhab-bot]

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/84

[netlify]

✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).

Built without sensitive environment variables

Name	Link
🔨 Latest commit	2f067b1
🔍 Latest deploy log	https://app.netlify.com/sites/openhab-docs-preview/deploys/67b9c1c9584c290008d30a01
😎 Deploy Preview	https://deploy-preview-2466--openhab-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).

Built without sensitive environment variables

Name	Link
🔨 Latest commit	c12de0a
🔍 Latest deploy log	https://app.netlify.com/sites/openhab-docs-preview/deploys/67d53d4e70204600081a583f
😎 Deploy Preview	https://deploy-preview-2466--openhab-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[jimtng]

I wonder if these rules should also be included in the documentation:
openhab/openhab-addons#12262

[andrewfg]

^
Yes. I will add them.

EDIT: but obviously such complex rules cannot be checked via the XSD schema validation in my other PR. ..

[andrewfg]

Also not expected to set "Status" tag on all read-only channel types.

@lolodomo can you please explain the above rule in more detail?

[andrewfg]

I added the rules from openhab/openhab-addons#12262 .. however I am not sure if I fully understand them all (in particular the last one) => @lolodomo can you please check them?

[openhab-bot]

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

[andrewfg]

Reviewers please IGNORE the lint error concerning numbered lists. Because in this case the numbering MUST flow on from one section to the next -- rather than re-starting from 1. in each section.

[rkoshak]

It looks good, I think there's some formatting and word choice things to address and it's good to go.

We may need to get buy in from core maintainers since they will be responsible for applying the rules in practice. Do the add-on maintainers need to buy in too?

[andrewfg]

@rkoshak many thanks for the feedback. I will upload a revised version soon. However for the time being let me address your question about where semantic tags can be applied:

Currently tags can be applied to the following objects with a chain of inheritance as follows:

• Channel-Type: Point/Property tags applied at design time via the channel type xml
• Channel: Point/Property tags inherited from Channel-Type above, and/or applied at run time in the binding
• Item: Point/Property tags inherited from Channel above, and/or all types of tags applied at run time by users

And yes, I am indeed working on a PR to extend the application of tags with a chain of inheritance as follows:

• Thing-Type: Equipment tag (single) applied at design time in the thing type xml
• Things: Equipment tag inherited from Thing-Type above, and/or applied at run time in the binding
• Semantic Model: Equipment tree structure ("create equipment from thing") inherited from Thing above, and/or by users

[andrewfg]

@rkoshak I just pushed a new commit; hopefully it addresses your feedback; but please feel free to comment further..

[rkoshak]

I'm happy with all the changes.

Also not expected to set "Status" tag on all read-only channel types.

I can't speak for @lolodomo but my understanding is this rule is to avoid the case where everyone just defaults to "Status". There Point tag should be the one closes to what the Item does. A temperature sensor should be a Measurement. However, a high temperature alert might be an Alarm. In both cases these represent a Status so Status is not incorrect. But there are better choices.

I think the rule is to use the more appropriate tags rather than defaulting to a generic tag.

[andrewfg]

I just pushed another commit with some more improvements.

• @rkoshak for the avoidance of doubt I removed the point where developers MAY add location tags; we can always add it back later if there is demand..
• @lolodomo can you please give feedback a) to the question above, and b) to the document in general?

[andrewfg]

@rkoshak whilst thinking about examples of possible POINT + PROPERTY combos, it occurred to me that POINT=LowBattery is probably a violation of our (just defined) rules ..

I think it should be POINT=Alarm + PROPERTY=Energy

(or POINT=Alarm + PROPERTY=Voltage).

[andrewfg]

@stefan-hoehn this PR is ready to merge.

[stefan-hoehn]

LGTM, thanks Andrew