Consistency check

[mkovatsc]

Editors of the other documents should file their concerns, change requests, etc. here in this issue. WoT Architecture Editors will use it as todo list.

[danielpeintner]

Besides some more general comments in https://github.com/w3c/wot-architecture/issues/37 I think we might want to adapt the list in https://w3c.github.io/wot-architecture/#wot-scripting-api w.r.t. Scripting API.

I propose to change three Sub APIs bullet list as follows (there is no Discovery API per se)

• WoT API to discover or retrieve consumed things and create exposed things

• Client API for consuming a thing by means of sending requests to servers in order to retrieve or update properties, invoke actions, and observe properties, actions and events.

• Server API to expose Things over the network and allowing for adding properties, actions, and events to a Thing.

@zolkis , @knimura, what do you think?

[zolkis]

That is correct.

[mkovatsc]

"WoT API" would be in conflict with "WoT Interface".

Why is it not called "Discovery API" anymore when it is to discover? I see the part of creating, but saw that as part of the Server API.

[mmccool]

I think we should avoid the term WoT API as it's too general and ambiguous (network API or scripting API)? We were previously using WoT API in the threat modelling document but were referring to the network interface, what we now call the WoT Interface. We plan to update all the terminology in the security sections to use WoT Interface.

I second the suggestion that we should name scripting sub-APIs after what they are for: Management API, Discovery API, etc. I also propose that we ONLY use API for things having to do with scripting (eg inside the runtime) and consistently use "Interface" for network interfaces (from outside things).

[zolkis]

Right, the generic term "WoT API" should be avoided and use specific terms like WoT Scripting API. We have a WoT object as the API entry point in scripting, hence the confusion :).

[zolkis]

In Scripting we are calling TD Repository a Thing Directory. Looking at the TD Repository term definition, it appears that Thing Directory would be shorter and more aligned with external terminology.

[zolkis]

In 3.1.4. Smart Home Hubs: these are not hubs, but gateways. Hubs tend to operate in the same connectivity realm.

[zolkis]

In 3.1.5. Cloud Device Shadows, "device shadow" IMHO could be expressed with existing terms (as it is done with the term proxy), no need to introduce a new term (actually it is not defined in Terminology) or even metaphor.

" device shadow is globally reachable"

This needs some more clarification, eventually add "by authenticated clients"?

[zolkis]

In 3.1.5.2. "Smart Home" hub should be "Smart Home gateway". Eventually give an example of hub, and gateway usage, respectively.

[zolkis]

In section 5, hub and gateway functionality is mixed, although "edge hub" is a comprehensible term. However, what appears to be called "device shadow" earlier, now it is called "digital twin" in Figure 9.

[zolkis]

A generic editorial comment: whenever a term defined in Terminology appears, it should be referenced in <a>term</a>. Also, as it normally happens, there are a few grammar and spelling errors that I don't cite here to avoid cluttering, but please check, especially in chapter 5.

[zolkis]

I suggest moving the last sentence from 5.4 to 6.2 and edit it according to the comment above.

[zolkis]

Section 6.6. WoT in the Web Browser needs some revamping, but this will surely be a hot target after the FPWD anyway :).

[zolkis]

In Section 7 check the use of hub vs gateway.

I would get rid of the structure Discovery/Connectivity/Security/API (half of them is just empty anyway) and replace it with understandable sentences. Besides, the term API is ambiguously used, as it touches elements from the protocol bindings.

[zolkis]

It is a bit misleading to have a security section in 5.5 larger than the proper section 8. At least a link from the former to the latter would be nice, to connect the two.

[zolkis]

Section 9. Conclusion is rather a Summary, and I wonder if it's needed at all.

[Kazuo-Kajimoto]

@zolkis In 3.1.5.2. "Smart Home" hub should be "Smart Home gateway". Eventually give an example of hub, and gateway usage, respectively.

Zoltan-san,

Terminology "gateway" and "hub", I have some confusion as you mentioned. Looking at Fig.9 and description about Fig.9, we can see "Edge Hubs" in Fig.9 and "the gateway level ("edge")" in the description. I think as common terminology, "hub" and "gateway" is the same.

On the other hand, in Japanese language, we have small nuance difference between "hub" and "gateway". Hearing the word "hub", we Japanese sometimes imagine the physical device. Hearing the word "gateway", we sometimes imagine not only physical device but gateway functionality. I'm not native English speaker, so I'm not confident the nuance difference is the same as you.

If there is no difference between the usage of "hub" and "gateway", then I agree woth you

[mmccool]

In networking, a "hub" typically refers to a passive device that does not route packets but broadcasts them. It is often used in contrast with a "router" (the term "hub" is in analogy to the hub of a wheel, which implies that it connects everything - eg broadcasts).

This is not the intended meaning here but might be confusing to some people. Therefore I agree that we should not use the term "hub" but be more specific and use "gateway". If we are talking about a network component (some subsystem available over the network) that offers additional services rather than just bridging two systems (for example, a fog compute system that offers computational services) then I would suggest use of the term "node" (as in an element of a graph).

[mmccool]

Also, Zoltan, regarding security, if we are going to properly cover all the elements of security necessary than it's going to get big. The IIC Security Framework is almost 200 pages long.

I personally don't think we need something THAT long but to even mention all the issues and threats will take a lot of space. Ideally we would just refer to an external document, which also lets us deal with overlapping concerns (for instance, as we have already run into with the TD) in one place. I think we should consider consolidating all the security considerations into a single document, publishing it as a note, and then just referencing it. This will also solve our problem with publication of the threat model.

Remind me to bring this up in the security meeting today. We already have a mandate to create a security repo, I think we should discuss having a separate security deliverable.

[mmccool]

Also, +1 on using Thing Directory rather than TD Repository.

Among other issues, the TD Repository term implies that it STORES the TDs but in fact we may only want to reference them (in case they are dynamically generated, for instance). A Directory is more general and includes the possibility of referencing (although, it could cache "static" TDs...).

I suppose an orthogonal issue is that maybe it should be a "TD Directory". However, I also vote for simplicity and I think "Thing Directory" is better.

[Kazuo-Kajimoto]

@zolkis

In Scripting we are calling TD Repository a Thing Directory. Looking at the TD Repository term definition, it appears that Thing Directory would be shorter and >more aligned with external terminology.

I agree "Thing Directory".

[zolkis]

For the sake of completeness, a WoT network element (in various physical networks) may have the following roles:

• an endpoint device,
• a hub,
• a bridge,
• a router or
• a gateway. A gateway directs traffic between heterogeneous networks, a router does it between similar networks.

If we say "WoT hub" that can indeed mean it's a device that bridges between WoT network elements in a single WoT network, even though it's not only a Layer 2 device.

But when we say "hub" in general, it means this.

So I suggest if we want to use the full term "WoT hub", meaning it's a node in a local WoT network that does not interface with any external network, then we should define it in terminology, and when the term is used, link it back to the definition with <a></a> tags.

However, my impression was that many of the given examples actually refer to a "WoT gateway" or gateway in general.

[mkovatsc]

I will do a pass over the document today integrating the comments here.

For now, I would suggest we only use the term gateway for that local element, as it is commonly used in IoT settings (meaning a more powerful local node that also has uplink capability). Over time, we might find relevant differences that will need special terms.

[mkovatsc]

BTW, we cannot have the <a> tags for defined terms when the terminology section is in another document. (I mentioned this as downside, when we decided to keep the terminology.md and link to it).

[zolkis]

We can have <a href="">...</a> tags there :)

[mkovatsc]

But no fragment addressing :) I will make them a link, also to emphasize.

[zolkis]

In Scripting, in the Terminology section, we define a list of terms with <dfn> and put one external link for the whole related list of terms. I think that's reasonable. Then, you can use <a></a> within the doc for all the terms.

[mkovatsc]

Well, you somewhat duplicated the used terms in the Scripting API doc. Doing this would be almost equivalent to just merging the Markdown terminology into the ReSpec Archtiecture document...

I will go with <a href="terminology.md">...</a>, which is then easily replaced when the term definitions are merged.

[zolkis]

Check again :). Mentioning terms does not equal to redefining them. The text/source reads like this:

<p>
  The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: 
  <dfn data-lt="Things">Thing</dfn>, <dfn data-lt="Thing Descriptions">Thing Description</dfn> 
  (in short <dfn>TD</dfn>), <dfn>Web of Things</dfn> (in short <b><i>WoT</i></b>),  
  <dfn>WoT Interface</dfn>, <dfn>Protocol Bindings</dfn>, <dfn>WoT Runtime</dfn>, 
  <dfn data-lt="consume|consume a TD|consuming a TD">Consuming a Thing Description</dfn>,
  <dfn>Things Directory</dfn> etc.
</p>

Then later in the doc we can say <a>WoT Runtime</a> and that takes the reader to the Terminology section - but more importantly, it emphasizes the fact that this is a defined term.

[mmccool]

Interesting hub vs. node discussion. I think one factor that tends to lean things towards the use of "hub" is the use of the Smart Home use case to drive the architecture. In that use case it is natural to talk about the hub, eg. the (singular) "central" house computer. In an industrial use case, "node" makes more sense, as you will tend to have a multiplicity of devices acting as concentrators, offload systems, etc. (eg it seems more natural to talk about "fog nodes").

I'm not suggesting we change anything though; we should go with common usage.

I do like Zoltan's reference to "hub" as a graph theoretical concept: a node in the graph with more connectivity than the average. With that definition multiple "hubs" are possible. Maybe in the definition of "WoT Hub" we can simply be explicit and say there is no implication that there is only one in a network (although we have to be careful elsewhere that we have architected the system to allow that: for instance, is more than one Thing Directory in a local network possible? Can they be federated/replicated etc?)

[mkovatsc]

Addressed final issues about Scripting API details and "hub" terminology in the deployment scenario figures (as mentioned above, for now we go for a consistent "gateway" terminology).