Semantic Tags: developer information/rules (#2466)
* improve information on tags Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * typo Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * adopt some reviewer suggestions Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * add further rules Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * fix lint error Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * import https://github.com/openhab/openhab-core/issues/4619 Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * tweaks Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * adopt reviewer suggestions Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * add rfc-2119 citation Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * cosmetics Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * fix capitalisation, and numbering scheme (to pass CI check) Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * adopt reviewer feedback Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * tweaks Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> --------- Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>pull/2474/head^2
Andrew Fiddian-Green
GitHub
parent
9682c3947a
commit
93b8256446
|
|
@ -0,0 +1,117 @@
|
||||||
|
---
|
||||||
|
layout: developersguide
|
||||||
|
title: Developer Guidelines on Semantic Tags
|
||||||
|
---
|
||||||
|
|
||||||
|
# Developer Guidelines on Semantic Tags
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
A semantic tag is an attribute of an openHAB [object](#objects-that-use-semantic-tags) that provides information to the openHAB User Interface about the type (i.e. the nature) of either things or items.
|
||||||
|
Note the use of the word `type`.
|
||||||
|
|
||||||
|
Semantic tags are divided into the following categories:
|
||||||
|
|
||||||
|
- EQUIPMENT (relates to the `type` of a piece of equipment)
|
||||||
|
- POINT (relates to the `type` of a particular data point within some equipment)
|
||||||
|
- PROPERTY (relates to the `type` of the information carried by a point)
|
||||||
|
- LOCATION (relates to the `type` of the location of an equipment or point).
|
||||||
|
|
||||||
|
## Purpose of Semantic Tags
|
||||||
|
|
||||||
|
The various equipment, points, properties, and locations are displayed in the openHAB User Interface in a hierarchical tree structure, which is based on a hierarchy of semantic tags defined in openHAB Core.
|
||||||
|
The primary purpose of semantic tags is to help the User Interface generate such a hierarchical tree structure of the user’s home system with its respective nested rooms, devices (things) and items.
|
||||||
|
Semantic tags are also used by HABot and end users in rules.
|
||||||
|
|
||||||
|
The purpose of this document is to provide rules for openHAB developers and openHAB maintainers in applying existing semantic tags as follows:
|
||||||
|
|
||||||
|
- By addon developers/reviewers at design time in the addon's `thing-type.xml` and `channel-type.xml` definitions.
|
||||||
|
- By addon developers/reviewers at run-time dynamically in the addon's Java code.
|
||||||
|
- By addon developers/reviewers in deciding whether to propose/approve a new semantic tag.
|
||||||
|
|
||||||
|
Note: the document may also provide information to help users when setting up their system.
|
||||||
|
|
||||||
|
## Objects that use Semantic Tags
|
||||||
|
|
||||||
|
Semantic tags can be applied to the following openHAB 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 the `Channel-Type` above, and/or applied at run time by the binding Java code.
|
||||||
|
- `Item` : POINT/PROPERTY tags inherited from the `Channel` above, and/or all types of tags applied users when setting up their system.
|
||||||
|
- `Thing-Type` : EQUIPMENT tag (single) applied at design time in the `thing-type.xml`.
|
||||||
|
- `Thing`: EQUIPMENT tag inherited from the `Thing-Type` above, and/or applied at run time by the binding Java code.
|
||||||
|
- `Semantic Model`: EQUIPMENT tree structure ("create equipment from thing") inherited from the `Thing` above, and/or by users.
|
||||||
|
|
||||||
|
## General Rules for Semantic Tags
|
||||||
|
|
||||||
|
The list of semantic tags defined in openHAB Core is extensible.
|
||||||
|
This document describes the developer rules for applying or extending this list.
|
||||||
|
|
||||||
|
The core predefined semantic tags are presented to users as propositions, suggestions, or hints.
|
||||||
|
It is possible for users to add their own customised tags at their own discretion.
|
||||||
|
The remainder of this document does NOT relate to user customised tags.
|
||||||
|
It applies solely to the openHAB Core tags.
|
||||||
|
|
||||||
|
This following uses terms "MUST", "MAY", "SHALL", "SHALL NOT", etc. that are defined in Internet Standard [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119)
|
||||||
|
|
||||||
|
### A. Rules for **APPLYING** Core Predefined Semantic Tags
|
||||||
|
|
||||||
|
1. Developers MUST apply core predefined tags in their addons where possible.
|
||||||
|
1. Developers MAY hard code the tags in the `thing-type.xml` or apply them dynamically at run time via the Java code.
|
||||||
|
1. Developers SHALL NOT apply LOCATION tags either in the `thing-type.xml`, or via the Java code.
|
||||||
|
1. Developers SHALL NOT apply customised tags in their addons.
|
||||||
|
1. Developers MAY apply a POINT tag without a PROPERTY tag (in cases where a property makes no sense). However, in such a case the developer MAY submit a new PROPERTY tag that fits.
|
||||||
|
1. Developers SHALL NOT apply a PROPERTY tag without a POINT tag.
|
||||||
|
1. Semantic EQUIPMENT tags MUST be applied at the thing level.
|
||||||
|
1. Semantic POINT and PROPERTY tags MUST be applied at channel level.
|
||||||
|
1. Developers MAY open a new PR to propose extensions to the core predefined tags as follows.
|
||||||
|
|
||||||
|
### B. Rules for **EXTENDING** Core Predefined Semantic Tags
|
||||||
|
|
||||||
|
The purpose of the semantic model is to provide a stable base set of tags for binding authors to use.
|
||||||
|
Submiting and adopting new tags should be a rare occurance.
|
||||||
|
|
||||||
|
1. New tags MUST fit within the hierarchy of semantic tags already defined in openHAB Core.
|
||||||
|
1. New tags SHALL NOT be synonyms of existing tags e.g. kitchen/kitchenette, sitting/living room.
|
||||||
|
1. New PROPERTY, POINT and EQUIPMENT tags SHOULD aim to be applicable across more than one binding.
|
||||||
|
1. Developers MUST provide supporting arguments in their PR that the rules above and below are met.
|
||||||
|
|
||||||
|
## C. Rules for extending EQUIPMENT Tags
|
||||||
|
|
||||||
|
An EQUIPMENT tag describes the equipment type of a piece of equipment.
|
||||||
|
Examples are thermostat, pump, car, wall switch, push button, alarm system, or alarm detector.
|
||||||
|
|
||||||
|
1. New EQUIPMENT tags MUST describe the equipment type of a physical or virtual device.
|
||||||
|
1. New EQUIPMENT tags MUST be a noun.
|
||||||
|
|
||||||
|
## D. Rules for extending POINT Tags
|
||||||
|
|
||||||
|
A POINT is a tag that describes the functional type (or purpose) of a data point within an equipment.
|
||||||
|
Examples are measurement, control, set point, or status.
|
||||||
|
|
||||||
|
1. New POINT tags MUST describe the functional type (or purpose) of the data point.
|
||||||
|
1. New POINT tags MUST be what you (the binding) does to, or how you (the binding) gets, the state of the Item.
|
||||||
|
1. New POINT tags SHOULD be defined in conjunction with an information type in a PROPERTY tag. See examples [below](#examples-of-point-and-property-tags).
|
||||||
|
|
||||||
|
## E. Rules for extending PROPERTY Tags
|
||||||
|
|
||||||
|
A PROPERTY is a tag that describes the information type (or content type) of the data produced or consumed by a point.
|
||||||
|
Examples are temperature, brightness, on-off, time stamp.
|
||||||
|
|
||||||
|
1. New PROPERTY tags MUST describe the information type (or content type) of the point.
|
||||||
|
1. New PROPERTY tags MUST be a noun and represent some attribute commonly controlled or sensed in a home automation context.
|
||||||
|
1. New PROPERTY tags MUST be defined in conjunction with the functional type of a POINT tag. See examples below.
|
||||||
|
|
||||||
|
### Examples of Point and Property Tags:
|
||||||
|
|
||||||
|
- A humidity sensor would have POINT=`Measurement` plus PROPERTY=`Humidity`.
|
||||||
|
- A thermostat's target temperature would have POINT=`Setpoint` plus PROPERTY=`Temperature`.
|
||||||
|
- A smoke alarm would have POINT=`Alarm` plus PROPERTY=`Smoke`.
|
||||||
|
|
||||||
|
## F. Rules for extending LOCATION Tags
|
||||||
|
|
||||||
|
A LOCATION is a tag that describes the location type of a point.
|
||||||
|
Its most common use case is to assign equipment to a location.
|
||||||
|
Examples are ground floor, dining (eating) room, kitchen (cooking room), living room, or garage.
|
||||||
|
|
||||||
|
1. New LOCATION tags SHALL NOT be synonyms of existing tags (see [rule B.2.](#b-rules-for-extending-core-predefined-semantic-tags))
|
||||||
|
|
@ -220,8 +220,19 @@ The following snippet shows a 'Control' and 'Light' tags definition:
|
||||||
</tags>
|
</tags>
|
||||||
```
|
```
|
||||||
|
|
||||||
Please note that only [Point](https://openhab.org/javadoc/latest/org/openhab/core/semantics/model/point/package-summary.html) and/or [Property](https://openhab.org/javadoc/latest/org/openhab/core/semantics/model/property/package-summary.html) tags from the pre-defined tag library should be used.
|
There are two possible types of tag -- namely "Semantic" and "Non Semantic" tags.
|
||||||
See also the [Semantic Model]({{base}}/tutorial/model.html) for more information on how tags are used with items.
|
The former are used by the openHAB User Interface to create automatic groupings of items according to the [Semantic Model]({{base}}/tutorial/model.html).
|
||||||
|
The latter are (optionally) be used for any other tagging purpose at the discretion of the user.
|
||||||
|
Semantic tags are classed into four sub-types `point`, `property`, `equipment` and `location`.
|
||||||
|
|
||||||
|
Addon developers are strongly requested to provide tags in the channel description and thing type XML.
|
||||||
|
Note: it is also possible to provide tags in instantiated channels and things at run-time.
|
||||||
|
When providing such tags, developers shall comply with the [Developer Guidelines on Semantic Tags](semantic-tags.md).
|
||||||
|
|
||||||
|
You can view the actual list of [Semantic Tags](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.semantics/model/SemanticTags.csv).
|
||||||
|
The contents of this list are dynamic, and it may be extended from time to time.
|
||||||
|
If you are an addon developer and you think there is something missing from the list please open an [Issue](https://github.com/openhab/openhab-core/issues) or [Pull Request](https://github.com/openhab/openhab-core/pulls) on GitHub.
|
||||||
|
Please make sure you comply with the [Developer Guidelines on Semantic Tags](semantic-tags.md) and the [Semantic Model]({{base}}/tutorial/model.html).
|
||||||
|
|
||||||
### State Description
|
### State Description
|
||||||
|
|
||||||
|
|
@ -817,7 +828,7 @@ The full Java API for bridge and _Thing_ descriptions can be found in the Java p
|
||||||
| description | A human-readable description for the channel | optional |
|
| description | A human-readable description for the channel | optional |
|
||||||
| category | The category for the channel, e.g. TEMPERATURE | optional |
|
| category | The category for the channel, e.g. TEMPERATURE | optional |
|
||||||
| tags | A list of default tags to be assigned to bound items | optional |
|
| tags | A list of default tags to be assigned to bound items | optional |
|
||||||
| tag | A tag semantically describes the feature (typical usage) of the channel e.g. AlarmSystem. There are no pre-default tags, they are custom-specific | mandatory |
|
| tag | A tag semantically describes the feature (typical usage) of the channel e.g. AlarmSystem. See [Default Tags](#default-tags) above. | mandatory |
|
||||||
| state | The restrictions of an item state which gives information how to interpret it | optional |
|
| state | The restrictions of an item state which gives information how to interpret it | optional |
|
||||||
| state.min | The minimum decimal value of the range for the state | optional |
|
| state.min | The minimum decimal value of the range for the state | optional |
|
||||||
| state.max | The maximum decimal value of the range for the state | optional |
|
| state.max | The maximum decimal value of the range for the state | optional |
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue