Motivate why bacv:usesService term is needed

[danielpeintner]

The term bacv:usesService seems to be easily linked to the op value (at least according to the examples).

e.g., "op": [ "readproperty" ] --> "bacv:usesService": "ReadProperty"

Since I am pretty sure that there is a reason why we need the additional term bacv:usesService I think it makes sense to motivate the reason in the binding document.

[ektrah]

The TD spec defines a vocabulary for WoT operations:

readproperty, writeproperty, observeproperty, unobserveproperty, invokeaction, queryaction, cancelaction, subscribeevent, unsubscribeevent, readallproperties, writeallproperties, readmultipleproperties, writemultipleproperties, observeallproperties, unobserveallproperties, queryallactions, subscribeallevents, unsubscribeallevents

BACnet defines a vocabulary for BACnet services:

Object Access Services: AddListElement, RemoveListElement, CreateObject, DeleteObject, ReadProperty, ReadPropertyConditional, ReadPropertyMultiple, WriteProperty, WritePropertyMultiple

Alarm and Event Services: AcknowledgeAlarm, ConfirmedCOVNotification, ConfirmedEventNotification, GetAlarmSummary, GenEnrollmentSummary, SubscribeCOV, UnconfirmedCOVNotification

...

So they are two different vocabularies, even if they contain a few very similar terms. Do you have a suggestion how this could be better presented in the document?

[danielpeintner]

Do you have a suggestion how this could be better presented in the document?

I don't have a good suggestion, but IF TD op values can "always" match the BACnet services I would think we don't need the term bacv:usesService at all. Not sure though.

The BACnet binding document could create a table instead like

TD op	BACnet usesService
readproperty	ReadProperty
writeproperty	WriteProperty
...	...

EDIT: I see that this mapping exists already, https://w3c.github.io/wot-binding-templates/bindings/protocols/bacnet/#default-mappings

[ektrah]

I think it's just a coincidence that some of the terms from the different vocabularies are almost the same. We shouldn't try to optimize anything here.

Suggestions for making it clearer in the document that there are two different vocabularies are welcome. Otherwise I would suggest closing this issue.

[fennibay]

The reasons for introducing bacv:usesService were:

1. To be able to distinguish between SubscribeCOV and SubscribeCOVProperty, both implementing the observeproperty operation -> then we decided to handle this by leaving out the property ID in the IRI
2. Other bindings had something similar, e.g. htv:methodName, cov:method
3. In case (1) happens for other services in the future (e.g. ReadRange), having some flexibility to distinguish.

We could add a blurb at the beginning of the section https://w3c.github.io/wot-binding-templates/bindings/protocols/bacnet/#default-mappings, something like:

In order to keep WoT InteractionAffordance operations loosely-coupled to BACnet services, bacv:usesService is modeled separately than the operation of the form. Since most cases the BACnet service is evident from the operation, this section documents the default mappings. In corner cases bacv:usesService can be used to specify the service to be used.

Or we can also close the issue.

[egekorkan]

The term should be definitely kept. Otherwise, we would need to write something like "Change the capitalization of the first letter and get the BACnet term" which is quite weird in my point of view.

[danielpeintner]

I am fine with closing. What I was trying to say is that a TD does not necessarily need to contain for example "bacv:usesService": "ReadProperty" IF it can be always added/mapped according to "op": [ "readproperty" ].

To me, it is a bit like in the HTTP binding, where "op": [ "readproperty" ] maps to "htv:methodName": "GET".
I think I need to add htv:methodName only if it maps to something else, don't I?

[fennibay]

To me, it is a bit like in the HTTP binding, where "op": [ "readproperty" ] maps to "htv:methodName": "GET". I think I need to add htv:methodName only if it maps to something else, don't I?

Exactly. If the default mapping suits your needs, you can omit bacv:usesService.

This also helps for avoiding repeating the form when the only difference is bacv:usesService, e.g. you can use one form with "op": ["readproperty", "writeproperty", "observeproperty", "unobserveproperty"], as long as you have the same href etc.

---

So, shall we close or add this blurb?

[danielpeintner]

So, shall we close or add this blurb?

I am fine either way. What do others think?
Perhaps we shouldn't make it any more complicated than necessary...