Add Architecture as a normative deliverable

[mlagally]

Adding an incremental architecture update

---

Preview | Diff

[egekorkan]

@mlagally thanks for the PR. However, as expressed in #16 , nobody seems to want a normative Architecture deliverable. I agree with the text you have proposed but even that does not motivate a normative specification. I think the text should be conserved and simply taken to the informative deliverables section.

[sebastiankb]

Agree, we should learn from our current situation and terminate the normative dependency in the future. This will simplify the standardization work with the other deliverables. In addition, topics like the effortful implementation report would be no longer necessary.

The architecture as Note should provide the overall picture of WoT, which is then implemented by corresponding self-contained normative deliverables (TD, Discovery, Profile, etc).

[mmccool]

Regarding the other comments about making this informative, I would agree with making Architecture informative IF there was another place to put normative security content. So if we get rid of Architecture as a normative document, I would want to see a "Security and Privacy" normative document added.

[benfrancis]

@mmccool wrote:

Regarding the other comments about making this informative, I would agree with making Architecture informative IF there was another place to put normative security content. So if we get rid of Architecture as a normative document, I would want to see a "Security and Privacy" normative document added.

What security and privacy assertions are there which could not be moved into Privacy & Security Considerations sections (or other sections) of the other existing normative specifications (Thing Description, Discovery and Profile)?

[mmccool]

Proposal:

• For charter, move Architecture to "informative" deliverables.
• We will have to come up with a plan to relocate other assertions; putting then into other specs may be appropriate.
• We should spend the Architecture call tomorrow to discuss the existing assertions and whether it would be feasible.

[egekorkan]

The other proposal is at #85

[mmccool]

@mmccool wrote:

Regarding the other comments about making this informative, I would agree with making Architecture informative IF there was another place to put normative security content. So if we get rid of Architecture as a normative document, I would want to see a "Security and Privacy" normative document added.

What security and privacy assertions are there which could not be moved into Privacy & Security Considerations sections (or other sections) of the other existing normative specifications (Thing Description, Discovery and Profile)?

To reply to this specific comment, things like required TLS versions for greenfield WoT implementations. These don't really apply to TD, since TD is about describing implementations, not constraining them. They don't apply to Discovery, since discovery is about finding TDs. They might be moved into profiles, but these security assertions are meant to apply to ALL greenfield implementations, so it would have to be a "universal" profile that automatically applies to greenfield implementations, e.g. even without a specified profile declared in the TD. In my opinion this would be awkward, and easily overlooked by implementors.

My preferred solution would be (as was previously proposed) to have a new, normative security document for this content, and also for things like onboarding (if we have it).

Note that some of the objections to the assertions in this section are that they are about implementation properties that are hard to test or that we don't have examples of, like support for secure updates or HAL safety checks. Unfortunately, just because something is hard or that we haven't gotten around to implementing these (or verifying that they exist already in implementations) doesn't mean they aren't necessary.

[egekorkan]

About a specific comment from @mmccool :

so it would have to be a "universal" profile that automatically applies to greenfield implementations, e.g. even without a specified profile declared in the TD. In my opinion this would be awkward, and easily overlooked by implementors.

I think that these kind of security assertions in the architecture spec are already overlooked by implementors. If Architecture assertions are only about security assertions at the very end of the document, they will be overlooked.

I think we should evaluate if a separate normative security document is the way to go. I think it would not hurt from an architectural perspective but I am not sure if we can sustain the workload it would require. If we cannot drive that work, we MUST move those assertions to the respective specifications.

[benfrancis]

@mmccool wrote:

things like required TLS versions for greenfield WoT implementations. These don't really apply to TD, since TD is about describing implementations, not constraining them.

Thing Descriptions are for describing both greenfield and brownfield devices. I think it would be perfectly fine to make these kinds of recommendations in the Security Considerations section of the Thing Description specification. There are already other similar assertions there such as:

• "To limit the scope and duration of access to Things, tokens SHOULD be used to manage access."
• "Thing Descriptions SHOULD be obtained only through mutually authenticated secure channels."
• "If it is necessary to fetch a context definition file, an implementation SHOULD first attempt to use HTTP over TLS even when only an HTTP URL is given. "

They might be moved into profiles, but these security assertions are meant to apply to ALL greenfield implementations, so it would have to be a "universal" profile that automatically applies to greenfield implementations, e.g. even without a specified profile declared in the TD.

I would suggest that the Thing Description specification is the universal default profile. It already makes lots of assertions like those made in profiles, profiles just narrow options further for interoperability.

In my opinion this would be awkward, and easily overlooked by implementers.

I agree, but to be honest I've implemented the Thing Description specification multiple times and I didn't realise many of those security assertions in the architecture specification existed. IMO they should be in the Thing Description or Discovery specification so that they are self-contained.

My preferred solution would be (as was previously proposed) to have a new, normative security document for this content, and also for things like onboarding (if we have it).

I don't think that's necessary, I think the assertions would be better accommodated in the Security Considerations sections of the Thing Description and Discovery specifications. That would reduce the number of documents that implementers need to read, and also be one fewer normative specification the Working Group needs to maintain.

If there really are security related assertions which don't fit into another existing specification but they are only recommendations and not "MUST", then they could be placed in the non-normative WoT Security Best Practices document. Assertions which only apply to greenfield implementations are by necessity just recommendations for Things (since brownfield Things may not be able to conform), and Consumers may also have to support Things which don't conform to those recommendations.

[mlagally]

The security requirements are horizontal requirements, that are applicable for all building blocks.
There are more horizontal parts in the architecture that do not belong anywhere else, e.g. the normative system architecture, which introduces intermediaries and consumers.
The concepts of WoT Servients, exposed things, consumed things are part of the normative sections of architecture and go beyond the scope of the TD.
As we discussed multiple times in architecture calls, a TD is describing only things.

These other system components do not have any other specification (yet).
We might consider defining a "Consumer description" at some point in time.

[egekorkan]

@mlagally I agree that there are interesting parts that can be kept normative, but it does NOT change the fact that implementors simply overlook these. If we have such requirements, they should be more visible and thus either to the respective specs or a new document like WoT Horizontal Requirements. We are shooting ourselves in the foot by putting these to the end of a document that starts with a generic overview and suddenly gets super specific about the normative requirements for implementations.

Regarding Runtime-related assertions: We are so far away from this and these are really implementation-specific assertions like "A WoT Runtime implementation SHOULD provide a hardware abstraction layer for accessing the native device interfaces.". Do you think that we should assert something like this in WoT?

[mryuichi]

I agree with @mlagally . WoT includes not only things but also intermediate things that connect consumed things, exposed things, and consumed things. It also defines a directory for finding TDs.

Architecture document contains a description of the internal architecture, such as the building blocks of a Thing, but also a description of the overall architecture that combines the above components. For example, the figure in chapter 5.11, chapters 6.1, 6.10 and 9. These are necessary descriptions for system integration. The architecture document should includes how to connect to the directory that registers TDs for searching, the configuration when consumed things are executed on gateways and clouds (using intermediary), shadow handling and edge processing. Also, there should be a normative description of how to combine components from multiple developers.

I think the enrichment of the TD and other documents has made WoT more attractive to companies developing IoT devices. Now it's time to appeal to those who use these to provide solutions. At present, there may be few people who are interested in consumed things and intermediaries. However, some of our customers have benefited from WoT because the solution is easier to maintain, even as the number of connected devices increases.

[mryuichi]

Regarding Runtime-related assertions: We are so far away from this and these are really implementation-specific assertions like "A WoT Runtime implementation SHOULD provide a hardware abstraction layer for accessing the native device interfaces.". Do you think that we should assert something like this in WoT?

I agree with @egekorkan on this point.
This Runtime is not necessarily required to implement a thing. So I think that the description of the internal architecture of thing should be rewritten according to the actual implementation.

[mmccool]

Summary:

• Are there normative statements that need to apply to WoT as a whole? And are these more than just security? Comments above: yes.
• Is WoT "glue" or "full stack"? We do not have a firm decision on this, and this impacts other decisions
• Kaz: we should focus on the specification and not the assertion and testing
• Ege: not close to full stack, but going there; what to do in the meantime; components that can be used on their own? Does a full-stack WoT system NEED discovery, for example?
• Luca: activity with profiles it way to bind together parts that should work together; problems are different for legacy systems
• McCool: If we assume that normative statements about WoT as a whole, then it follows that a central normative document like Architecture is needed.
• Ege: Full stack would imply things like conformance testing, etc. Is it even feasible? Also quite concerned about visibility of assertions.
• Luca: Think we should leverage the profiles: link assertions, test suites, etc.
• Kaz: should look at assertions in all docs

[mmccool]

Proposal:

• Keep Arch as normative for now
• Do further work to address issues, i.e. visibility, in internal structure of documents
• Work on refactoring across documents during the next charter, making sure that "global" normative content ends up in Architecture and not scattered around

[benfrancis]

Counter-proposal:

• Make Architecture 2.0 an informative Note which provides an introduction to the WoT building blocks and how they fit together
• Remove all normative assertions from the Architecture specification, or move them to one of the other normative specifications, or Security Best Practices document, where appropriate

I've started a detailed spreadsheet of all the assertions in WoT Architecture with proposals of where to move the assertions to. Each assertion would need to be evaluated to decide whether it really needs to be an assertion, e.g. because it duplicates or is implied by other assertions in other specifications, or could just be turned into informative explanatory text.

[relu91]

Is WoT "glue" or "full stack"? We do not have a firm decision on this, and this impacts other decisions

Not sure how the full stack term is used here, but yes, IMHO, it impacts the future of the Scripting API too.

[mmccool]

As we discussed yesterday, we decided to make architecture normative - for now - but add a plan for refactoring to the scope section.

[benfrancis]

As we discussed yesterday, we decided to make architecture normative - for now - but add a plan for refactoring to the scope section.

Sorry, I only saw a proposal, not a resolution.

I hope you will re-consider this decision following TAG feedback on the charter, or that WoT Architecture will become non-normative by default through re-factoring out assertions into the specifications in which they belong. I think it would really help implementers if the TD and Discovery specifications were more self-contained.