Change description for 'observable' to reflect its purpose

[sebastiankb]

Since we agreed to make op mandatory (also see https://github.com/w3c/wot-thing-description/issues/405) the role of readOnly and writeOnle changed. Both should address the data schema definition and less the operations in the forms.

In that sense the role of the observable also changed and can be reflected by the op value 'observeproperty'. Proposal is to remove this duplicated and inconsistency susceptibility term from the PropertyAffordance.

Please comment on it.

[sebastiankb]

One motivation for keeping the term would be to the WoT API producer and properties setup. The observable term can be used as an indication for the communication layer to establish an observable property and provide this information in the TD.

My suggestion would be to make a decision in the next TD version and keep the term.

[mmccool]

Note that the proposed ThingTemplates don't have forms, and therefore no ops. So we cannot infer whether a property is observable (or read-only, or write-only) from the (missing) forms in this case. It boils down to whether you think the observable (or read-only, or write-only) status is an attribute of the abstract interaction or "just" a protocol-level property. After having worked on the communications diagrams in the Architecture doc, I have come to the conclusion that since they affect how the ConsumedThing and ExposedThing interactions behave, these are part of the definition of the Interaction abstraction. Therefore it makes sense to keep them, and perhaps even resurrect readOnly and writeOnly (although I still find those terms confusing... but, for consistency with JSON-schema perhaps we are stuck with them).

Under this interpretation, the values of these flags in a property define attributes of the interaction. Then we need an assertion saying that the ops in a protocol binding (that is, in the forms) MUST be consistent with these flags. In particular, if the "observable" flag is set, then ANY protocol binding must include at least one form with an "observeproperty" operation.

The following is perhaps slightly beyond the scope of this issue: For read and write, I personally would prefer also to see parallel "readable" and "writeable" flags... if we MUST have readOnly and writeOnly, I would prefer to make them mutually exclusive (users can only specify one) and then readOnly means you can read but not write, and writeOnly means you can write but not read. Maybe we can have "readable" and "writeable" too and make these flags be shorthand for setting these to true/false and false/true? Sigh...

[takuki]

@mmccool , what do you mean by "resurrect" readOnly adn writeOnly? They are still there. I was also in the opinion that we should preserve them since op is a protocol binding concept.

[sebastiankb]

in today's TD meeting we think it is the best for now to keep it

[mkovatsc]

No arguments were presented why to keep this term. It has no functional purpose, as the ability to observe must be provided through the form hypermedia control.

[mkovatsc]

One option would be to keep it with an updated definition:

A hint that indicates whether Consumers should observe the Property to automatically receive change notifications, but also for Intermediaries whether they should provide the observe capability for this Property.

However, we once had the term stability, which is basically an improved version of observable, as it provides a numeric value on which more fine-granular decisions can be made. This is useful in constrained environments, where only a limited number of Properties can be made observable.

Thus, the over option is to replace it with a stability vocabulary term.

[zolkis]

It has no functional purpose, as the ability to observe must be provided through the form hypermedia control.

That is fine.

stability, which is basically an improved version of observable, as it provides a numeric value on which more fine-granular decisions can be made

That looks like a scaled/translated version of how often a value might change, which would be mean of the change frequency. If we specify stability, we should also specify the algorithm to compute it (based on change frequency).

[mkovatsc]

@sebastiankb could you at least update the description for observable?

A hint that indicates whether a remote client can subscribe to ("observe") the Property, to receive change notifications or periodic updates (true/false).

to

A hint that indicates whether Servients hosting the Thing and Intermediaries should provide a Protocol Binding that supports the observeproperty operation for this Property.

[sebastiankb]

done

[mkovatsc]

Looks good. Closing.