A start on use cases and requirements for Profiles 2.0 #417
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,74 @@ | ||||||||||||||||||||
| # WoT Profiles 2.0 Use Cases & Requirements | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ## Introduction | ||||||||||||||||||||
|
|
||||||||||||||||||||
| The [Web of Things](https://www.w3.org/WoT/) (WoT) seeks to counter the fragmentation of the [Internet of Things](https://en.wikipedia.org/wiki/Internet_of_things) (IoT) by using and extending existing, standardized web technologies. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| The [W3C WoT Thing Description 1.1 specification](https://w3c.github.io/wot-profile/#bib-wot-thing-description11) defines an information model and JSON-based representation format for describing the capabilities of connected devices and the interfaces with which to communicate with them. Thing Descriptions are designed to be protocol-agnostic and flexible enough to describe a wide range of existing ("brownfield") IoT devices. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| In order to provide this level of flexibility the Thing Description specification includes a number of extension points including protocol bindings, payload bindings, security mechanisms, link relations and semantic contexts. As long as all of the capabilities of a device can be described using a Thing Description and a [Consumer](https://w3c.github.io/wot-profile/#dfn-consumer) implements all of the extensions used, the Consumer should be able to interoperate with that device. However, the result of this extensible architecture is that any given Consumer can only interoperate with a subset of possible [Web Things](https://w3c.github.io/wot-profile/#dfn-thing). | ||||||||||||||||||||
|
|
||||||||||||||||||||
|
|
||||||||||||||||||||
| "WoT Profiles" are a mechanism by which out-of-the-box interoperability between WoT [Consumers](https://w3c.github.io/wot-profile/#dfn-consumer) and [Things](https://w3c.github.io/wot-profile/#dfn-thing) can be guaranteed, by constraining a Thing to a finite list of options for each extension point, and requiring that it conforms to certain defaults. As long as a Consumer implements all of the extensions and defaults prescribed by a Profile, it should be guaranteed to be able to use all of the capabilities of a Thing which conform to that Profile, without Thing-specific customisation. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| Profiles will be designed specifically for new ("greenfield") implementations where developers have the freedom to conform to a prescriptive protocol binding and set of common constraints, in order to benefit from this additional level of interoperability. | ||||||||||||||||||||
|
There was a problem hiding this comment. I think this is the part that may see contention. WoT Greenfield is just another ecosystem's Brownfield. In order of having established ecosystems converge/evolve to WoT more easily we should have more than ad-hoc compatibility for them. There was a problem hiding this comment. I'm surprised by this, because until recently I thought this was a key differentiation that everyone agreed on. Of course I agree that today's "greenfield" is tomorrow's "brownfield", but really the important point here is the distinction between the "descriptive" approach of protocol binding templates vs. the "prescriptive" approach of profiles. In WoT 1.0 there are essentially two separate approaches to WoT - Binding templates (poorly named IMO) are best for describing existing systems where the communication interface can not be changed, whereas profiles provide a template (🤔) for new implementations which have the freedom to conform to a common standard in return for an increased level of interoperability. In WoT 2.0 I'm proposing that bindings and profiles work better together, with profiles adding an optional layer of prescriptive constraints on top of bindings. I don't see any benefit in using Profiles to describe existing IoT platforms, that's what platform bindings are for. However, given there now seems to be some resistance to the greenfield/brownfield terminology I have reworded this paragraph to say:
Is that any better? |
||||||||||||||||||||
|
|
||||||||||||||||||||
| ## Use Cases | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As a developer of a WoT Consumer, I want to guarantee out-of-the-box interoperability with a wide range of WoT Things. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As a developer of a WoT Thing, I want to guarantee out-of-the-box interoperability with a wide range of WoT Consumers. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Smart Home | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As the developer of DIY smart home hub software, I want to safely expose an HTTP-based API for monitoring and controlling a home which conforms to a common standard, so that cloud services from multiple vendors can add value to a user's smart home without having to implement a vendor-specific API. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As the developer of a smart home mobile app, I want to offer my users out-of-the-box interoperability with a wide range of smart home devices so that I can maximise the audience for my app. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As the developer of a smart home device, I want my device to be controllable by any smart home hub software and/or any smart home mobile app that conforms to a common standard.... | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Smart Buildings | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As the developer of a smart building hub, I want to safely expose an HTTP-based API for monitoring and controlling a commercial building which conforms to a common standard, so that cloud services from multiple vendors can consume data from that hub without having to implement a vendor-specific API. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| As the developer of a smart building cloud service, I want to be able to provide data analytics for smart buildings using smart building hubs from different vendors which conform to a common standard, rather than having to implement multiple vendor-specific APIs. | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Smart Cities | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Manufacturing | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Energy | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Transportation | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### Agriculture | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ## Requirements | ||||||||||||||||||||
|
|
||||||||||||||||||||
| ### WoT Profiles Specification | ||||||||||||||||||||
|
|
||||||||||||||||||||
| The WoT Profiles specification: | ||||||||||||||||||||
| 1. MUST define a mechanism by which the author of a WoT Thing Description can denote that the Thing it describes conforms to a particular profile | ||||||||||||||||||||
| 2. MUST define a registry of profiles to which WoT Things and WoT Consumers may conform | ||||||||||||||||||||
| 3. SHOULD aim to keep the number of registered profiles as small as possible by rejecting profiles that significantly overlap in technologies or use cases, in order to minimise fragmentation on the Web of Things | ||||||||||||||||||||
| ### Individual Profiles | ||||||||||||||||||||
|
Comment on lines
+55
to
+58
There was a problem hiding this comment. These are not dependent nor subsequent requirements; each stands on its own. Therefore, this should be an unordered list (bullets) not ordered (numbers). If there is a specific need to refer back to individual requirements, each requirement in these two lists (including the sub-requirements) SHOULD be given its own permanent identifier (URI), which can be used in future documents here and elsewhere.
Suggested change
There was a problem hiding this comment. I started the Use Cases & Requirements document as a Markdown file for simplicity, and as far as I know GitHub Markdown doesn't support anchors in list items. A numbered list seems like a reasonable way of making individual requirements referenceable. If someone wants to turn this into a more formal HTML document using ReSpec (which supports such things) then feel free, but I've done this before and for this kind of document I tend to think it just makes the document harder to edit. There was a problem hiding this comment.
Drat. Markdown constantly surprises me with features it lacks, especially its site-to-site variance.
It's reasonable if it's reasonably-well guaranteed that the members of such lists will never change order or meaning, or at least that substitute "blanks" that say something like "this item has been deleted in favor of..." will be inserted to ensure that external references will always reach the appropriate item or such a "blank". Even then, it would be better to have number+short-title referenceability. All things considered, including the W3C Priority of Constituencies, I would strongly advise conversion to ReSpec or Bikeshed, with an appropriate anchor for each requirement. There was a problem hiding this comment. Bikeshed feels the easiest way forward IMHO. |
||||||||||||||||||||
|
|
||||||||||||||||||||
| Individual profile documents: | ||||||||||||||||||||
| 1. MUST specify an identifier (URI) which identifies the profile | ||||||||||||||||||||
| 2. SHOULD constrain a finite set of protocol bindings that a conformant Thing may use and that a conformant Consumer can be expected to support | ||||||||||||||||||||
| 1. MAY constrain conformant Things to always follow certain defaults defined in a protocol binding document | ||||||||||||||||||||
| 3. SHOULD constrain a finite set of payload bindings that a conformant Thing may use and that a conformant Consumer can be expected to support | ||||||||||||||||||||
| 1. MAY constrain conformant Things to always follow certain default payload formats defined in a payload binding document | ||||||||||||||||||||
| 2. MAY constrain conformant Things to follow certain conventions such as date formats and error formats | ||||||||||||||||||||
| 4. SHOULD constrain a finite set of security mechanisms that a conformant Thing may use and that a conformant Consumer can be expected to support | ||||||||||||||||||||
| 5. SHOULD constrain a finite set of discovery mechanisms that a conformant Thing may use and that a conformant Consumer can be expected to support | ||||||||||||||||||||
| 6. MAY constrain a finite set of link relation types that a conformant Thing is recommended to use, and how they should be interpreted by a WoT Consumer | ||||||||||||||||||||
| 7. MAY constrain a finite set of semantic contexts that a conformant Thing is recommended to use and that a conformant Consumer can be expected to support | ||||||||||||||||||||
| 8. SHOULD NOT directly extend the WoT Thing Description information model, which should be defined using TD context extensions | ||||||||||||||||||||
| 9. SHOULD NOT define protocol behaviour, which should be defined in a protocol binding document | ||||||||||||||||||||
| 10. SHOULD NOT define data payload formats, which should be specified in a payload binding document | ||||||||||||||||||||
| 11. SHOULD NOT define discovery mechanisms, which should be defined in the WoT Discovery specification | ||||||||||||||||||||
| 12. SHOULD NOT define security mechanisms, which should be defined in a protocol binding document | ||||||||||||||||||||
| 13. SHOULD NOT describe an existing single-vendor IoT platform, which should be defined in a platform binding document | ||||||||||||||||||||
| 14. MUST NOT include any assertions which would require a Thing Description of a conformant Web Thing to be non-conformant with the Thing Description 2.0 specification | ||||||||||||||||||||
| 15. SHOULD NOT include any assertions which conflict with another Profile, so that a Thing may conform with multiple Profiles | ||||||||||||||||||||
|
There was a problem hiding this comment. Do we want to allow a thing to describe something outside of the profile scope? e.g. a thing may sport an http profile that covers only properties and all the properties then have an http form constrained by the profile, but it can also provide coap forms and event affordances in the same description. The consumer then may just ignore them or process them using the degraded consumption rules we should write down in the TD document. There was a problem hiding this comment. Yes, and there is a note to this effect in the existing 1.0 specification. I've added this note the end of the introduction. |
||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the Oxford comma is a matter of taste ;)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To a degree. In my experience, using it eliminates possible (and never adds) confusion, while leaving it out often (though not always) leaves possible confusion, so I almost always recommend it in spec-type documents.