Architecture Restructuring

[mmccool]

Architecture Restructuring

• Some "Pillars": Terminology; Deployment Patterns; then Building Blocks and Abstract Architecture.
• Edit: Also, general statements about Security and Privacy.
• Feedback
  • bad, doc is too big, 6-7-8 are not synched well enough with other specs (impression from Luca B in TD call);
  • good, business people appreciated 4 & 5 (use cases and domains), supported business use cases.
• Editor's call was useful for synchronizing various documents.
• Maybe have a TF (probably Arch) whose job it is too synchronize TFs, maybe doc to collect common specs.

[mmccool]

Some thoughts on restructuring:

• Use cases and usage patterns material could be moved to the Use Cases and Requirements document. Some summary could remain, e.g. the single figure of usage patterns.
• Should remove assertions about TD, Discovery, etc. and let those documents be self-contained. These assertions are easy to overlook, which makes testing, validation, etc. more difficult. Architecture should focus on describing the building blocks and how they fit together.
• We do need to add more material around security (e.g. onboarding, which fits in with lifecycle), which will be normative.

[k-toumura]

I generally agree with @mmccool's thoughts.

• The Architecture document could be more compact document, that focuses on the contents of chapters 6,7,8,10,11 to explain the building blocks and giving pointers to other documents (to avoid overlapping or contradictory descriptions).
• In some cases, I think that security/privacy-related contents (chapter 10,11) could also be moved to a separate document and make Architecture document non-normative.

[mryuichi]

Generally agree with @mmccool .

Regarding chapter 9, I think it would be nice to leave some parts as explanations when building a large-scale system. It's now titled Example, so it should be changed. Figure 14 illustrates system integration and shows that WoT can handle large scale use cases. In smart cities, where many factories, buildings, and houses are connected from the cloud, intermedairys will be connected in multiple stages and aggregated. Additionally, intermediary may process data as edges.
In Chapter 7, the internal structure of Thing is shown as building blocks, but I think it is necessary to describe the integrated architecture that combines the system components shown in 6.10 and the WoT Thing Description Directory (TDD) as an architecture document.

[egekorkan]

We had an internal discussion about this.

• We are in favor of making the document informative.
• The two types of content in the document need some thinking to correctly place them (like said by @k-toumura and the initial comment by @mmccool which was my comments from an arch call).
• We should handle the terminology section such that other normative specs that link to its definitions do not show errors in respec.

By the way, there has been a TAG review saying this document should be a Note. See here.

[mlagally]

Editor's call was useful for synchronizing various documents.
Maybe have a TF (probably Arch) whose job it is too synchronize TFs, maybe doc to collect common specs.

I agree very much to this.

Synchronization among TFs should be an ongoing process and coordinated on a regular basis.

A single horizontal document that lays the common ground for all WoT specs is necessary, which defines the system components, building blocks and their relationship.
Privacy and security is a horizontal requirement on all building blocks, as well as terminology and overarching concepts.
This document should also describe at a high level the use cases and requirements that are addressed by these building blocks.

A first time reader should get an overview about the purpose and applications of WoT without having to read multiple specifications.

[egekorkan]

@mlagally I agree with your points above. However, I do not think that any of this requires the arch spec to be normative. So many of the assertions in the current spec are either irrelevant and not-implementable in the current WoT building block implementations or can be moved to respective specifications.

[benfrancis]

I don't mind too much about the document structure but I agree with @mlagally that WoT Architecture is a useful introduction to WoT which explains the different building blocks and how they fit together.

I also agree with @egekorkan /Siemens, @k-toumura and the TAG that the next version of the document should be non-normative and any remaining normative assertions should be moved into the other normative specifications so that they are more self-contained.

[mmccool]

Notes from Security TF call:

• Discussed whether it would be better to have normative security content in Architecture or in a new normative Security document
• Consensus was that since it is still unclear whether we will be doing onboarding, and without it the normative security content is relatively short, it would be better to leave the normative security content in Architecture (which means Architecture would be normative).
• If we DO do onboarding, it can go into Architecture in this round, and we can look at refactoring it in a later round (a next-next charter) into a separate Security doc.
• Since the charter is relatively short we should do refactorings in relatively small steps. We don't have years to stabilize new refactored documents.
• Also, we agreed that Onboarding does not belong in Discovery.

[benfrancis]

Consensus was that since it is still unclear whether we will be doing onboarding, and without it the normative security content is relatively short, it would be better to leave the normative security content in Architecture (which means Architecture would be normative).

I can see why this justifies not having a separate normative security deliverable, but you don't say why the small number of normative security assertions could not be moved to the TD and Discovery specifications (and potentially the non-normative Security Best Practices document), instead of remaining in Architecture and forcing that entire document to be a REC.

Also, we agreed that Onboarding does not belong in Discovery.

Could you explain why?

[mmccool]

Consensus was that since it is still unclear whether we will be doing onboarding, and without it the normative security content is relatively short, it would be better to leave the normative security content in Architecture (which means Architecture would be normative).

I can see why this justifies not having a separate normative security deliverable, but you don't say why the small number of normative security assertions could not be moved to the TD and Discovery specifications (and potentially the non-normative Security Best Practices document), instead of remaining in Architecture and forcing that entire document to be a REC.

Because the security assertions are generally about WoT implementations as a whole, and are prescriptive. The WoT TD is about describing things (providing metadata), whereas the security assertions actually constrain implementations to satisfy certain properties.

We could put them into the TD spec, but they don't really "fit".

Also, we agreed that Onboarding does not belong in Discovery.

Could you explain why?

Similar argument to above. It could go into Discovery but Onboarding is logically a separate step in the lifecycle from Discovery. It's true however that you would often follow onboarding (key provisioning, pairing, etc) immediately with registration in a TDD. It's also true that we could make TDD registration a mandatory part of onboarding, but this is not the only possibility. I don't think the Security TF was entirely against it, and it could probably be made to work, but the general feeling was that onboarding fits in better with a general discussion of lifecycle.

[benfrancis]

@mmccool wrote:

Because the security assertions are generally about WoT implementations as a whole, and are prescriptive. The WoT TD is about describing things (providing metadata), whereas the security assertions actually constrain implementations to satisfy certain properties.

Thank you for explaining, but having read over all of the security assertions in WoT Architecture I'm not sure I recognise the distinction. Either an assertion needs to be satisfied by a WoT Consumer/Thing implementation or it doesn't. Security is not implemented in isolation, but as part of either a Consumer, Producer or Thing. There may be different recommendations for greenfield Things than for brownfield Things, but they are still Things.

• Assertions that need to be satisfied when implementing a Consumer or Producer of Thing Descriptions should be in the Thing Description specification
• Assertions that need to be satisfied when implementing a Consumer or Producer of discovery mechanisms should be in the Discovery specification
• Assertions that need to be satisfied when conforming to a Profile should be in the Profile specification

It could go into Discovery but Onboarding is logically a separate step in the lifecycle from Discovery.

From what you've explained so far I'm not even sure that onboarding should be within the scope of WoT, but if it is then it isn't really about the architecture of WoT, but a concrete mechanism within it like Discovery. If it doesn't belong in one of the existing specifications then maybe it's better to incubate it as as a separate deliverable published as a Note within this charter period, which could become (or be added to) a normative specification once it's clearer where it fits?

Please see my proposal for WoT Architecture 2.0 in #82 (comment)

[mmccool]

Made normative for now (PR #82), will however consider doing refactoring during the course of the charter.