A start on use cases and requirements for Profiles 2.0

[benfrancis]

Following on from my strawman proposal for Profiles 2.0, I think it's important that this time around we agree on a clear set of use cases and requirements up-front before we start work on the specification.

With this in mind I have made a start on a Use Cases & Requirements document which so far includes:

• Introduction - A preamble including recent text from the existing 1.0 specification which describes the general motivation for profiles
• Use Cases - A start on a collection of generic and domain-specific use cases based on my own direct experience, plus an initial set of headings for other potential application domains as an invitation for others to add their own use cases
• Requirements - An initial set of proposed requirements for a Profiles 2.0 specification (which would just define the profiling mechanism and a registry of profiles) and for individual profile documents

I welcome your feedback.

[lu-zero]

The wot-uc group has this form for submitting new use-cases, we planned to give it a test with the TD taskforce, but we could try also for profiles.

[TallTed]

Suggested change

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).

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).

[benfrancis]

I think the Oxford comma is a matter of taste ;)

[TallTed]

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.

[TallTed]

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

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.

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 members of a class of 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 member of a class of [Thing](https://w3c.github.io/wot-profile/#dfn-thing), without Thing-specific customization.

[benfrancis]

@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.

[TallTed]

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

	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
	* 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
	* MUST define a registry of profiles to which WoT Things and WoT Consumers may conform
	* 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

[benfrancis]

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.

[TallTed]

GitHub Markdown doesn't support anchors in list items.

Drat. Markdown constantly surprises me with features it lacks, especially its site-to-site variance.

A numbered list seems like a reasonable way of making individual requirements referenceable.

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.

[lu-zero]

Bikeshed feels the easiest way forward IMHO.

[TallTed]

Suggested change

	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
	* MUST specify an identifier (URI) which identifies the profile
	* SHOULD constrain a finite set of protocol bindings that a conformant Thing may use and that a conformant Consumer can be expected to support
	* MAY constrain conformant Things to always follow certain defaults defined in a protocol binding document
	* SHOULD constrain a finite set of payload bindings that a conformant Thing may use and that a conformant Consumer can be expected to support
	* MAY constrain conformant Things to always follow certain default payload formats defined in a payload binding document
	* MAY constrain conformant Things to follow certain conventions such as date formats and error formats
	* SHOULD constrain a finite set of security mechanisms that a conformant Thing may use and that a conformant Consumer can be expected to support
	* SHOULD constrain a finite set of discovery mechanisms that a conformant Thing may use and that a conformant Consumer can be expected to support
	* 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
	* 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
	* SHOULD NOT directly extend the WoT Thing Description information model, which should be defined using TD context extensions
	* SHOULD NOT define protocol behaviour, which should be defined in a protocol binding document
	* SHOULD NOT define data payload formats, which should be specified in a payload binding document
	* SHOULD NOT define discovery mechanisms, which should be defined in the WoT Discovery specification
	* SHOULD NOT define security mechanisms, which should be defined in a protocol binding document
	* SHOULD NOT describe an existing single-vendor IoT platform, which should be defined in a platform binding document

[benfrancis]

@lu-zero wrote:

The wot-uc group has this form for submitting new use-cases, we planned to give it a test with the TD taskforce, but we could try also for profiles.

That seems very overcomplicated for our needs, and I would be concerned that all the mandatory fields will deter people from contributing.

Perhaps we could compromise on something structured but simpler, like a user story:

As a _______ I want to _____ so that ________

Application domain: [Smart Home|Smart Buildings|Smart Cities|Manufacturing|Energy|Transportation|Agriculture|Other]

---

Rather than formatting and grammar, I'm much more interested in feedback on the actual content. Does this match people's understanding of what profiles are and what they are used for?

I'm keen to assess the level of consensus around that because I'm concerned from the past few months of discussions that there's still a lack of a basic shared understanding.

[danielpeintner]

My point of view ...

[benfrancis]

I've also added a requirement to try to make it clear that a Thing should be able to conform to multiple profiles.

[lu-zero]

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.

[benfrancis]

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:

Whilst the Web of Things provides the freedom to describe a wide range of existing IoT systems using Thing Descriptions, Profiles provide an optional additional layer of common constraints to which new implementations can conform in order to benefit from an increased level of interoperability.

Is that any better?

[lu-zero]

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.

[benfrancis]

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.