Suggestion to establish an official naming convention

[jlaur]

I hereby propose to establish a naming convention for addons for the following reasons:

• To achieve cross-binding consistency in names exposed to users, such as thing type ids and channel ids.
• To have some guidelines for developers, eliminating doubt when trying adopt existing de-facto conventions.
• To reduce time needed for advising about and discussing naming in pull request reviews.

Historically it seems there has never been an official naming convention. I don't know if there were any previous attempts to gain consensus, but it seems the only documented naming convention is actually one that was never agreed upon for channel ids: openhab/openhab-docs#1492. I have been referencing this when reviewing pull requests, unfortunately without knowing this history.

The goal is to gain consensus and as a result create an official naming convention that should be used for new bindings.

The initial proposal is the following:

• thing type id: lower-case-hyphen
• channel type id: lower-case-hyphen
• channel group id: lower-case-hyphen
• channel id: lower-case-hyphen
• thing property: camelCase
• config parameter: camelCase
• profile URI: lower-case-hyphen
• profile type id for transformations: UPPER_CASE
• XML files in src/*/resources: lower-case-hyphen.xml

Each of these proposals can be discussed separately. If you agree or disagree to any of them, please add your input (with arguments when disagreeing).

The proposals are mostly based on consistency with the de-facto naming in core, and also in many existing bindings, although there is a lot of variations here.

Additionally some specific arguments up front:

• Config parameter: camelCase allows mapping to config classes while maintaining the usual convention for java field naming (@J-N-K)
• Thing property: Compatibility with parameters: discovery → properties → parameters

[wborn]

I like it and agree with the arguments made!👍It's good to have some standardization. But I wasn't notified of the post so I will see if it helps to also tag the @openhab/maintainers. 🙂

[jlaur]

Other opinions, especially from @openhab/add-ons-maintainers?

• Should we establish a naming convention?
• Should it be the proposed one?

[ccutrer]

I like it, as long as we're aware there are a large number of bindings that likely won't be updated to follow it anytime soon, or ever.

What's the strategy for bindings that generate dynamic channels, such as MQTT Homie and Home Assistant? I want to improve the legibility of their generated type and channel ids already. It's okay in such cases to not strictly follow the convention, correct? That's less of a question, and more of a statement, since the mapping often needs to be two-way, and while some IDs can translate back and forth correctly without munging, doing something like translating from lower-case-hyphen to camelCase and back may not be lossless. So it's either violating the naming convention a bit, OR the other choice is what is currently done, where type IDs go through an encoding step which will still violate the naming convention, while also making IDs far less readable.

Example: I have a channel corresponding to an MQTT config topic at homeassistant/switch/easytouch2-4p/easytouch2-4p-3-slide with a unique ID of poolController-3-slide. Right now the full channel ID is mqtt:homeassistant_easytouch2_2D4p:mosquitto:easytouch2_2D4p:poolController_2D3_2Dslide#switch, while if I abandon the unnecessary encoding (Home Assistant IDs will fit nicely within the allowed characters for openHAB IDs), I could get that down to mqtt:homeassistant:mosquitto:easytouch2-4p:poolController-3-slide#switch. Which violates the channel group ID (hybrid camel case, hybrid hyphenated), but if I were to try and force that to be pool-controller-3-slide, it could theoretically conflict with another perfectly valid unique Home Assistant ID, and it wouldn't be possible to unique map back to poolController-3-slide (should it be poolController3Slide or pool-controller-3-slide??)

[jlaur]

I like it, as long as we're aware there are a large number of bindings that likely won't be updated to follow it anytime soon, or ever.

The general idea would be to require the convention to be followed for new bindings. For existing bindings, I would generally suggest to follow the existing conventions used. This would at least keep consistency within the particular binding rather than introduce mixed naming which seems counter-productive. In case of major refactoring, there might be opportunities to migrate to this naming convention, but that wouldn't be a hard requirement, just a possibility. The Hue API v2 PR could be such an example.

MQTT would already be covered by this "legacy rule". Even if this wasn't the case, there could be good reasons for deviating from the naming convention. It would require good arguments, like you just provided, so I think this could be decided on a case by case basis. For me the most important gain would be having some general guidelines that cover most scenarios and thus eliminate doubt and increase consistency.

[kaikreuzer]

@jlaur I agree that it makes sense and there should have been such a convention right from the start, which we unfortunately never established. As for your suggestions: As they reflect the de-facto standard right now, I don't have any change requests.

[jlaur]

As next step, since there has been no vetoes yet, I have created a draft PR: openhab/openhab-docs#2061. Any other opinions before publishing?

[obones]

Sorry to be late on this, I have just started to write addons.
If I read the recommendation correctly, I would need to change my description from this:

		<channels>
			<channel id="name" typeId="name"/>
			<channel id="onOff" typeId="onOff"/>
			<channel id="heatStage" typeId="stage"/>
		</channels>
		<properties>
			<property name="vendor">AirZone</property>
			<property name="thermosType"/>
			<property name="thermosFirmware"/>
			<property name="thermosRadio"/>
		</properties>

to this:

		<channels>
			<channel id="name" typeId="name"/>
			<channel id="on-off" typeId="on-off"/>
			<channel id="heat-stage" typeId="stage"/>
		</channels>
		<properties>
			<property name="vendor">AirZone</property>
			<property name="thermosType"/>
			<property name="thermosFirmware"/>
			<property name="thermosRadio"/>
		</properties>

Am I correct?

I'm not saying the choices are bad, but wouldn't it feel strange to have two naming conventions in the same XML definition file for a thing type?
Either way is fine by me, I just want to make sure I understood things properly