Terminology about wot-architecture

[draggett]

In regards to the definition for "Thing"

An abstraction of a physical entity whose metadata and interfaces are described by a WoT Thing Description.

This is too narrow and should be broadened to include abstract entities, e.g. "physical or abstract entity".

Abstract entities include virtual things as compositions of other of things. Abstract entities also include virtual things as abstractions of other services, e.g. cloud based services. This simplifies applications compared to having to deal directly with the underlying protocols involved.

[draggett]

In regards to the definition for "Servient", I think we should distinguish the case of a client only stack, e.g. a web page library. We can also mention the role of cloud based servients that re-publish things provided by hubs/gateways behind a firewall.

[draggett]

Do we want to add a new term to cover re-publishing a thing, e.g. when a thing is provided by a device or application hub behind a firewall, or by a device with limited ability to handle lots of connections.

[draggett]

In regard to the definition for "WoT Runtime', shouldn't we also note the use of the popular terms "hub" and "gateway"? A hub hosts applications. A gateway provides the mean to bridge different protocols and standards, as well as establishing security boundaries, something important given the security risks of connection embedded devices directly to the Internet.

[zolkis]

In my understanding, publishing or registering a Thing means to announce/provision it to the network (i.e. a network element or cloud/database) after which the Thing becomes identifiable and discoverable in the network. It does not mean it's always reachable. When it comes online after a break, it doesn't need to register again, unless it wants to be re-provisioned with a different identification.

In the case when proxies or directories cache Things, the question is identification: only one entity with a given ID should respond to requests, i.e. either a copy cache of a device gets a different ID, or it owns/represents the original device in the sense the device is not directly exposed to the network any more. In that case the publishing entity is the directory on behalf the device, identified with one ID.

[zolkis]

A hub hosts applications.

Do you mean that a hub is an "extension" (in a separate device) to Things that are not capable of running a WoT Runtime, to represent them with added scripting capabilities? A hub then would be able to represent one or more Things, but all in the same network, protocol, and security realm, such as Bluetooth devices in a room?

In contrast, a gateway would be able to do the same, but supporting multiple network/protocol/security realms?

From WoT point of view, I don't see principial difference between the hub and gateway, and the security (cross-network/protocol/policy) paradigm needs to be encapsulated anyway. Maybe I misunderstood the difference between hub and gateway.

[mkovatsc]

@draggett

This is too narrow and should be broadened to include abstract entities, e.g. "physical or abstract entity".

We received critique for defining a Thing to be anything. Thus, for now, we (a sub-group that discussed this) prefer this definition, which does include virtual Things as compositions of other of Things as well. Let's see the public feedback.

"Servient", I think we should distinguish the case of a client only stack

See "WoT Client"

cover re-publishing a thing

Can be clearly expressed with common terminology, i.e., "proxy Thing" / "proxying Thing" / etc.

note the use of the popular terms "hub" and "gateway"

I would have said, hub and gateway are -- as you say -- popular, common terms that would not need definition. Zoltan's comment might proof otherwise, although all his assumption meet my understanding as well as your understanding of the terms...

[zolkis]

To expand a bit more on my last comment; in my view, both a WoT hub and gateway share the following traits (of a WoT servient):

1. separate device with connectivity (exposed in one or more networks, and able to connect to one or more types of endpoint devices)
2. provisioned with a SW stack that contains drivers, libraries and other building blocks WoT protocol bindings can configure for the WoT interactions defined in consumed and exposed TDs.
3. run WoT Things as services in a WoT Runtime
4. optionally the WoT runtime MAY run and manage scripts.

Now in my view, it is only a deployment issue whether 1) supports multiple connectivity types and networks, 2) supports multiple protocol stacks. But we can still distinguish between hub and gateway in the well known common sense - this distinction is not in WoT terms, but in common terms.

So while the terminology we use is WoT Servient, in common sense we can talk about hubs and gateways and IMHO we don't need to define WoT terms for these. When we say "WoT gateway" we mean a WoT Servient with gateway capability and mode, and similarly, "WoT hub" means a WoT Servient in hub mode (even if the device has capability to function as gateway, just not deployed that way).

[draggett]

@mkovatsc

This is too narrow and should be broadened to include abstract entities, e.g. "physical or abstract entity".

We received critique for defining a Thing to be anything. Thus, for now, we (a sub-group that discussed this) prefer this definition, which does include virtual Things as compositions of other of Things as well. Let's see the public feedback.

In discussions with people outside of the IG/WG I have always had broad support for using things for physical and abstract entities. RDF provides a general means to describe physical and abstract entities, and the property/action/event paradigm is essentially about object oriented design. I would like to see the critique you mention as I suspect it is based upon a lack of appreciation of RDF and object oriented design principles for software systems.

[draggett]

@mkovatsc

cover re-publishing a thing

Can be clearly expressed with common terminology, i.e., "proxy Thing" / "proxying Thing" / etc.

That misses the point that the proxy is republished as a thing, i.e. the proxy has its own thing description and communication metadata. Moreover, this is typically set up at the request of another servient, e.g. a hub behind a firewall. This has important implications for the binding templates and APIs.

[mmccool]

I am strongly in favor of broadening (or keeping the broadness of) the definition of Thing to include services ("virtual entities"). We're already intending to do this anyway for "System" Things to represent services like storage, etc. The definitions of terms should represent what the abstraction is actually being used for.

I suppose, as an alternative suggestion, we could have Thing and Service being subclasses of a more generic concept (Object?) but I think that's overly complex. It's easier to just use a broad definition of Thing.

It's also notable that the Thing Description includes relatively little information about the physical component of a Thing, and such information is basically optional, being represented with semantic tagging via extension points. In contrast, the network interactions of a Thing are not optional and are given in detail. So if a Thing is something that can be described by a Thing Description, then it's a service that can respond over the network, and is only optionally associated with a set of physical actuators and sensors.

[mmccool]

The current abstract is basically written with the point of view that a Thing is an IoT service optionally associated with a physical device. I see there is an editor's note to "polish" the abstract, but I think that is a related issue to this terminology (well, actually, a pretty fundamental definition) discussion.

I did the last revision of the abstract so I think it reflects my point of view, possibly more than others. So probably someone else should do the next revision in case I am an outlier...

[mmccool]

Regarding the "hub" issue, I just did a pass over the text and I think it will be too hard to change the hub terminology globally without a huge number of edits. There is also the problem that "Smart Home hub" does seem to be a commonly-accepted term for what we are talking about but "Smart Home node"... not so much.

So we may have to leave this alone for now.

[mkovatsc]

Definition of Thing

Broadening the definition of "Thing" while keeping it in scope now reads:
"A Thing is the abstraction of a physical or virtual entity that needs to be represented in IoT applications."

Hub issue

Already fixed in the Architecture document.
TD and Scripting API documents do not use the term.

Abstract

I added the note based on your comments that all document abstracts still need work.
I will do my iteration and remove the note to be ready for publication.

"TD Vocabulary" and "domain-specific vocabulary"

I added strawman definitions for both.
Since I do not have a strong semantics background, they should be improved.
Can be done after the FPWD release, since markdown...
@vcharpenay maybe you can give it a shot :)

Re-publishing a Thing

"Proxy" exactly covers your concerns about being republished as a Thing with its own TD and potentially different Protocol Bindings. A proxy is a different instance than the original, a surrogate that can have its own added functionality (e.g., caching on the Web). The idea of Manger Things covers your use case of instantiating proxy Things on behalf of another Servient or the proxied Thing itself.
I think, rather than squeezing this into a definition, this is better dealt with providing the deployment scenario / guideline / design pattern to explain it in detail.

[draggett]

@mkovatsch - I've found it valuable to distinguish the creation of a proxy for the sole use of a given application from the cases where a proxy is published for use by other applications. We could perhaps use the terms "sole use" and "shared use" for this distinction.

As an example of the former consider an application that is implemented as a web page and uses a web page library to create an object in the page's script execution environment where the object acts as a proxy for a remote thing. This object is only available to the web page running on a particular browser.

As an example of the latter, consider the case where a thing representing the home's heating system is created by an app running on a home gateway and republished on a cloud server for access by applications on authorised smart phones. This involves the cloud server hosting a proxy for the thing and providing a thing description for accessing the proxy on that server.

[vcharpenay]

The expression "Linked Data vocabulary" is not widely used in the Semantic Web community. The terms "Web ontology", "RDF vocabulary" or "Semantic Web vocabulary" seem more suitable to me (in order of preference). Here is a alternative proposal:

TD Vocabulary

Machine-readable specification of the TD Interaction model and the communication metadata of WoT Binding Templates, in the form of a Web ontology referenced by a TD.

Domain-specific Vocabulary

External Web ontology referenced by a TD (distinct from the TD vocabulary) that covers a particular domain of activity (such as building automation, product manufacturing, mobility, etc.) and that may or may not be aligned with the TD Interaction model.

[zolkis]

It would be nice to include or convey a concise, coherent relationship between

• WoT runtime (or Servient, though I prefer Runtime, since it's defined in browsers and it is a known equivalent term), defined by a service for WoT requests
• WoT Interface which is the interface provided by the WoT Runtime
• Scripting API that is an API interface provided to ease the implementation of, or extend a WoT Runtime, either available in provisioning phase (producing a flashable image, or a form of deployment outside of normal operation mode), or consumed by a separate service, e.g. a special script management Thing in the WoT Runtime.
• Protocol Bindings as an optimisation/standard way to implement a WoT Runtime.

These relationships are be needed in the Security document.

[mlagally]

@draggett @zolkis @mkovatsc @mmccool @vcharpenay I believe this has been addressed either in the TD spec or the current architecture draft. Please review until 26.2.

[mkovatsc]

After working on the definition sections in the Architecture document, I gained the feeling that our terminology section has many unnecessary definitions. One example is "WoT Client": I don't see the need to define this, as the well-known term "client" already covers what we want to say. If we are in the context of WoT, it is clear that it is a client for WoT. When there are other ecosystems, it is natural language to clarify to WoT client or, for instnace, OCF client.

I think we should critically check each terminology entry.

[mkovatsc]

About the last comments here:

"sole use" and "shared use" for proxies

The "sole use" corresponds to instantiating a software object of Thing in the local runtime. It is clear that nobody outside the runtime can access unless it is exposed.

The "shared use" emerges once a software object is exposed.

I personally do not see the need to define the terms "sole use" and "shared use",

WoT runtime (or Servient, though I prefer Runtime, since it's defined in browsers and it is a known equivalent term), defined by a service for WoT requests

@zolkis Could you please provide the browser definition for "runtime"?

Historically, we have been calling the full software stack the Servient, in which the runtime system is just one component. To my understading, the WoT Runtime is the environment in which the Thing software objects are instantiated. The WoT Runtime has to interface with protocol binding implementations (protocols stacks) southbound and an application API (e.g., WoT Scripting API) northbound. Furthermore, the WoT Runtime must be able to serialize its Exposed Things to a TD.

WoT Interface which is the interface provided by the WoT Runtime

The WoT Interface is the network-facing interface that is described by a TD. This requires the mapping rules of Protocol Bindings between the abstract WoT Runtime (Thing level) to a network-facing interface (protocol level).

Scripting API that is an API interface provided to ease the implementation of, or extend a WoT Runtime

I personally don't see how this relates to the common understanding of runtime systems. Maybe the sloppy use of "runtime" vs "runtime system" or "runtime environment" caused some deeper misunderstanding?

Historically, the "Runtime" in WoT refered to an execution environment for WoT programs/applications. The Scripting API provides a standardized API for applications to consume and expose Things, and define the application logic. It is not used to implement or extend the runtime system itself.

Protocol Bindings as an optimisation/standard way to implement a WoT Runtime

We now have: "Protocol Binding: The set of mapping rules from an Interaction Affordance to concrete messages of a specific protocol". These rules are encoded into the TD using forms.

Before we had "Protocol Binding: An implementation of the mapping between Interaction in the TD Interaction Model (e.g., Property read) and specific operations of a protocol (e.g., HTTP GET)." Here, the notion of implementation was too specific, as there may exist different implementations of the same rule set, which would provide the same Protocol Binding. Hence, it is not the implementation (concrete code) itself.

[mlagally]

@mkovatsc if we define the Runtime in issue 83, is there anything left to do for this issue?

[mlagally]

I cleaned up the terms from above in the terminology section.
Pull request: #115

[mkovatsc]

At this point, I actually doubt that we would need this term in the Architecture document. The only sensible place to introdce it is the Servient Implementation section, which describes one possible way to do it (informative). In general, the common and more correct terms "runtime system" and "runtime environment" cover what we need; I also think this works for security, as isolated runtime environments for multiple tenants are nothing new.