fixing terminology section

[mlagally]

cleanup terminology
#83
moving chapter 7.5 Interconnection of servients to chapter "9 WoT Deployments"
#110

[takuki]

My understanding is that Interconnection of servients section was meant to map building blocks to High-Level Architecture described in section 6.2. I am not so sure if the section fits well in WoT Deployments section.

I suggest @mryuichi to simplify Interconnection of servients section. It should show and explain how Things each loaded with building blocks connect to and work with one another in light of the high level architecture. I think a simplified version can stay in WoT Building Blocks section.

[k-toumura]

@takuki I agree with you about necessity of simplification of the 7.5 Interconnection of Servients section.

To incorporate this material to 7. WoT building block section, it should align a level of abstraction on the section. For example, ‘Servient’ and other implementation-oriented descriptions are suitable for 8. Servient Implementation or later sections, but not suitable for 7. WoT building block section.

Abstraction level of each section (just my consideration):

• 6. WoT Architecture: normative
  • Web Thing, Interaction Model, Protocol Binding (show approaches --- "By describing and complementing. Not prescribing a full-stack solution", as shown in WoT Introduction Slidedeck)
 --- to meet Requirements
• 7. WoT building block: normative, except 'WoT Security and Privacy Guidelines'
  • Thing Description, Binding Templates, Scripting API, Security and Privacy Guidelines (show how to describe what exists)
• 8. Servient Implementation: non-normative
  • Servient, Runtime (show how to implement Thing/Application using Building Blocks)
• 9. WoT Deployments: non-normative
  • Application Servient, Remote/Local Proxy Servient, Device Servient (show how to cover use cases and Requirements using Servients and other functions)

I think the simplification of this section need a considerable work, and currently @mmccool is also updating this section in PR #101. So, to avoid complicated conflict, I recommend to simply merge this PR, and after stabilize this section, @mryuichi may make another PR for simplified version of 7.5 Interconnection of Servients for 7. WoT building block.

[mlagally]

@takuki @k-toumura If we look at the current contents of chapter 7.5., which talks about interconnection of servients, I think that chapter 7 is not the right place for it.

In the current form chapter 7.5. fits best into chapter 8, which introduces the servient concept and describes how to implement the servient based on the building blocks. Chapter 7.5. introduces different types of servients and builds on the definitions and terminology introduced in sections 8.1-8.4.

I'll update the PR to move it to section 8 at this point - we can revisit, once section 7 is updated.

[mryuichi]

@mlagally I think the description of how to cooperate with the other servients is very useful to clarify the functionality of the servient. The Text of Chapter 7.5 is better to be kept in Chapter 7, because my intention to input this was not to specify the implementations of the servient. If you feel It is too detail, it's no problem to simplify.

As @k-toumura wrote, we should make consensus of the contents from chapter 6 to 9. My idea for the abstraction level of each chapter is different from @k-toumura.

6. WoT Architecture: normative
   High-level architecture, WoT principals like Interaction Model
7. WoT building block: normative,
   Overview of building blocks, Application Behavior, Interaction Affordance, Protocol Binding, Security configuration and Inter Connection of Servients (or Building blocks).
8. Servient Implementation: non-normative
   Detail configuration of Servient including Runtime (show its behaviors of how to create ExposedThing or ConsumedThing, etc.)
   Scripting API is a part of implementation.
9. WoT Deployments: non-normative
   Describe the implementations of more complicated configurations of servients.
   2 configurations ( "application and device", "application, proxy and device" ) has been described in the previous chapter.

[mlagally]

@mryuichi I agree that the description of how to cooperate among servients is very useful.
Also when I look at the chapter contents you are proposing and the structure proposed by @k-toumura there are many commonalities, so I hope the alignment will not be difficult.

However I am thinking about the following two aspects:

1. Chapter 7 is meant to explain and reference the other specifications, i.e. it only talks about things and thing descriptions, binding templates, the scripting API and the security guidelines.
   The chapters 7.1 - 7.4 do not contain the term "servient" at all. I can see use cases, where the building blocks can be used on devices, that don't adopt the servient model.
   The architecture should not prescribe the servient model as the only valid implementation of a WoT compliant device.
   A TD can describe a device that does not implement a server but acts as a client for an IoT cloud service.
   Conceptually it is structured with a TD and "exposes" functionality, however all communication is initiated from the device. This is the case for many IoT deployments with connected sensors, where the sensors most of the time just push data and only occasionally want to check for actions.

2. If I understand the core of your proposed structure correctly, the main difference is that the scripting API is moved to chapter 8. We have consensus that it is an optional building block, which can be used if needed.
   What would be different if we move it to chapter 8?

[mryuichi]

@mlagally Thanks for your comment. If the purpose of Section 7 is to explain other documents, it should be move to the beginning of this document, e.g. Section 1. I thing the main body of the document might be better to describe the specifications.