Dynamic update of Thing model may break clients

[mlagally]

The model of dynamic things has several consequences, that need to be carefully considered:

For the following discussion, imagine a network of multiple clients that are connected over unreliable connections. Not all clients may be always on, so when a change to the "Thing" happens, there are conditions, where one set of clients are aware of the new thing model and a second set of clients assumes the old thing model.
It also cannot be assumed, that all clients actually can/or want to support the new thing model, but rather want to continue using the old model.

This is an old problem in programming languages / libraries, where APIs evolve over time.
It is typically addressed by just permitting to extend the model, i.e. introduce additional properties, methods and events. This does not break the contract with the existing clients.
Another sensible way, that gives clients a chance to adapt to the changes, is to deprecate these items for a certain period of time, before they actually can be removed.

For all these cases it is essential to have a versioning mechanism to give clients a reliable mechanism to determine that a thing has changed.

[mkovatsc]

Thanks for tracking this here!

My short answer is that the resolution should work similar to the Web: error messages during runtime (cf. 404 Not Found) and metadata for recovery (e.g., link to updated, now valid TD).

Also, we should not think in the terms of tightly coupled systems, where there is a server version and a client version, and that is what defines interoperability. We target loosely coupled systems in the style of REST, where client and server can evolve independently. In case of an issue, a client should be able to-rediscover the service it needs; a fallback is fetching a software update or informing an operator.

[zolkis]

We target loosely coupled systems in the style of REST, where client and server can evolve independently. In case of an issue, a client should be able to-rediscover the service it needs; a fallback is fetching a software update or informing an operator.

I agree. Still, @mlagally is right, we want to be able to make WoT solutions that do not break existing services while still capable of evolving. That would mean a deprecation mechanism at least, i.e. the old version remains a running server on its own, and the new version is run as a separate Thing object. This would not need versioning.

AFAICT, this (i.e. implementing deprecation, versioning, and fallback mechanisms in WoT solutions) is already possible with today's TD definition and scripting API:

• one could define a solution specific version in the TD, so it does not need to be standardized.
• one could choose not to update the TD in existing objects, but create new objects with a changed TD from a script.
• one could implement fallback mechanisms in the handlers bound by the scripting API to the interaction handlers (property change, property retrieval, action invocation).

However, it would not harm to have a (relative) TD version number and a scripting API version number (exposed on the WoT object).

[mkovatsc]

A Scripting API version is only relevant to scripts, not WoT Clients. Also remember that the Scripting API is optional and Things can be implemented through native code. So implementing fancy solutions only here will not help. At is an issue at a much higher level.

The only useful thing to do here, might be to add text to the setHandler and remove functions that summarizes the implications.

Versioning the TD needs to be taken to the TD Task Force, so we end up with one standard field for this, is we want to counter silos with WoT.

[zolkis]

However, it would not harm to have a (relative) TD version number and a scripting API version number (exposed on the WoT object).

A Scripting API version is only relevant to scripts, not WoT Clients.

Would you enlighten me how the two sentences above are in contradiction? I have explicitly stated the script version number is on the WoT object. Where else do you have a WoT object if not in the scripting?

[mkovatsc]

TD version number

Versioning the Thing and expressing in its TD: +1

scripting API version number

Versioning the Scripting API: -1

Browsers don't do this either; WoT API should follow the same "currently implemented" approach.

If you talked about "script version" (note you wrote "scripting API version"), we don't need this on the object, as Things from different scripts should always communicate through the TD-described interface (even when it is a local binding). And how people will version their software artifacts is out of scope.

[zolkis]

As no one objected, we can take the comment above as consensus. If you disagree, re-open this issue.