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,69 @@ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| # 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). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| The WoT Profiles specification should complement the [Thing Description](https://w3c.github.io/wot-profile/#bib-wot-thing-description11) specification, by enabling ad-hoc interoperability through the use of "profiles". A profile prescribes a finite set of extensions and defaults that a Thing can be constrained to in order to guarantee out-of-the-box interoperability with any Consumer which implements that profile. Out-of-the-box interoperability means that a [Consumer](https://w3c.github.io/wot-profile/#dfn-consumer) is guaranteed to be able to use every capability of a [Thing](https://w3c.github.io/wot-profile/#dfn-thing), without Thing-specific customization. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
There was a problem hiding this comment. This might want further massage to be clear. Without something like this tweak, the last sentence suggests that a Consumer which has implemented any profile can use every capability of any Thing, not limited to Things that conform to the profile(s) implemented by the Consumer.
Suggested change
There was a problem hiding this comment. @TallTed Thanks for this feedback. The out-of-the-box interoperability definition was taken out of context from the current specification, I've tweaked the text and it's hopefully now more clear. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
benfrancis marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ### 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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.