Feedback on latest Editor's Draft

[benfrancis]

Following @sebastiankb's email regarding an internal review of the WoT Thing Description 1.1 specification with a view to publishing the next working draft, please find my feedback below.

This is part 1 of my feedback covering sections 1-5. Part 2 covering sections 6-11 to follow!

Abstract

• "a formal model" (potential for confusion with newly defined "Thing Model") -> "a formal information model"?
• "allows to describe" (grammatically incorrect) -> "allows authors to describe"?
• "IoT" is not defined

Unless otherwise specified, documents created with version 1.0 of this specification remain compatible with Thing Description 1.1.

• This may require further explanation since 1.0 and 1.1 Thing Descriptions have a different @context URI (see below). It would be good to have an explanation somewhere of what exactly is meant by backwards compatibility (see Definition of Backwards Compatibility #1243).

3 Terminology

Implementations of a TD Processor may be a TD producer only (able to serialize to TD Documents) or a TD consumer only (able to deserialize from TD Documents).

[x] I note that the WoT Architecture document has a definition of a "Consumer", but not a "Producer".

5 TD Information Model

5.3.1 Thing

• The vocabulary term securityDefinitions is missing from the table (there's a description but the actual term is missing).

The @context name-value pair MUST contain the anyURI https://www.w3.org/2022/wot/td/v1.1 either directly when of type anyURI or as first element when of type Array.

• I think some explanation is needed here about how a Thing Description 1.1 can be backwards compatible with the Thing Description 1.0, since the 1.0 specification makes the same assertion but with a different URI. See Definition of Backwards Compatibility #1243 for discussion and a suggested solution.

The solution I proposed in #1243 (comment) was:

A Thing Description can use the 1.0 context (if a valid 1.0 TD), 1.1 context (if a valid 1.1 TD) or both (if it's both a valid 1.0 TD and 1.1 TD). A 1.0 consumer can only be expected to parse a Thing Description which includes the 1.0 context, but can not be expected to parse a Thing Description which only has a 1.1 context. A Thing Description which only contains the 1.1 context should be a valid 1.1 Thing Description.

• This would require lifting the constraint that the URI https://www.w3.org/2022/wot/td/v1.1 must be first in the array, since both URIs can't be the first.

When the forms Array of a Thing instance contains Form instances, the string values assigned to the name op, either directly or within an Array, MUST be one of the following operation types: readallproperties, writeallproperties, readmultipleproperties, writemultipleproperties, observeallproperties, unobserveallproperties, queryallactions, subscribeallevents, or unsubscribeallevents.

• The combination of this assertion and op being a mandatory member of Form causes a problem for top level WebSocket endpoints of Things which provide operations other than those listed here. See Allow more operations in a top level form #1070 and op does not have with default tag anymore #1192 (comment) for further discussion. I propose either lifting this constraint, or making the op member optional.

The data schema for each of the property meta-interactions is constructed by combining the data schemas of each PropertyAffordance instance in a single ObjectSchema instance, where the properties Map of the ObjectSchema instance contains each data schema of the PropertyAffordances identified by the name of the corresponding PropertyAffordances instance.

• Note that there is currently no equivalent explanation for the actions and events meta-interactions (see Payload format for meta operations #1231). E.g. should the data schema of a queryallactions operation be a map of arrays, whose members follow the data schema for a queryaction operation (see Is there a need for invokeanyaction/queryallactions operations? #1200 (comment))? Is there an equivalent of this for events?

5.3.1.3 PropertyAffordance

This state can then be retrieved (read) and optionally updated (write).

• I think this text was meant to be changed in refactor: clarify that property can be retrieved and/or updated #1306 and accidentally reverted in add more urivariables examples #1315.

5.3.2 Data Schema Vocabulary Definitions

• "is reflecting" -> "reflects"

5.3.4 Hypermedia Controls Vocabulary Definitions

• "is reflecting" -> "reflects"

5.3.4.1 Link

• What is the manifest link relation type used for? The description "Point to a software implementation of the TD" is unclear. See What is the intended use of the manifest link relation? #1076. I'd suggest changing the description to something like: "Point to the web app manifest of a web application which provides a user interface with which a user can interact with the Thing." Note that this link relation type is defined in the Web App Manifest specification which could be provided as a reference.
• What is the proxy-to link relation type for? I can't find a definition in the (non-normative) WoT Security and WoT Binding Template documents cited as being the source.
• How do the collection and item link relation types relate to the Directory Service API in the WoT Discovery specification? I can imagine that a collection link could point to the TDD of a directory, but what would the item link point to? Or is this a completely separate mechanism which can be combined with a directory? If so, would a directory list all of the "item" TDs directly, or only the "collection" TD? Edit: I see that these link relation types are used in example Thing Models later in the specification.

5.3.4.2 Form

• Does the "with default" assignment on the op member also mean "mandatory" if no default is provided? In particular I'm thinking about top level forms for which no defaults are defined. (See comments above about the issues with op being mandatory for Form, discussed further in Allow more operations in a top level form #1070).

I welcome the table with definitions of operation types!

Identifies the queryallactions operation on a Thing to get the status of all Actions in a single interaction.

• I suggest making it explicit that this includes action instances for all interaction affordances, i.e. not just instances of a single action affordance (see How do you cancel or query the state of an action request? #302).
• Another small point, the definition of the term "queryallactions" probably shouldn't contain the term "queryallactions" (this applies to several operation types in the table).

5.3.4.3 ExpectedResponse

• I suggest that ExpectedResponse should have a schema member of type DataSchema, like AdditionalExpectedResponse does. See Consider adding DataSchema to response and additionalResponses #1053.

[benfrancis]

Feedback part 2 (sections 6-11) below...

Note: Apologies, this feedback ended up much longer than I had expected and now this issue is very long. Most of the major areas of feedback already have their own issues associated with them but I'm happy to break out other issues as requested. I haven't created separate issues for all the typos and grammatical errors I spotted since there are so many (you can find them all by searching for "->"), but hopefully they can all be fixed in one go (I can create a PR if I have time, but I may not have time before the end of the year). Obviously all of this feedback doesn't need to block publication of the next Working Draft and I am happy to re-purpose some of it as feedback on the published Working Draft later if preferred by the Editors, I just figured you'd rather receive it sooner rather than later.

6.3.1 Thing Root Object

The root element of a TD Serialization MUST be a JSON object that includes a member with the name @context and a value of type string or array that equals or respectively contains https://www.w3.org/2022/wot/td/v1.1

As in 5.3.1, care needs to be taken here with backwards compatibility. This assertion is probably OK because it doesn't require that https://www.w3.org/2022/wot/td/v1.1 be the first item in the array. So the following would be valid according to this assertion:

"@context": ["https://www.w3.org/2022/wot/td/v1", "https://www.w3.org/2022/wot/td/v1.1"]

However, the changes I proposed for section 5.3.1 would be needed in order for this to be valid.

6.3.2 Human-Readable Metadata

If this section contained a RECOMMENDATION that both the Thing Root Object and all properties, actions and events should include at least a title (and possibly a description), it would take a lot of heavy lifting away from the WoT Profile specification (see w3c/wot-profile#10, w3c/wot-profile#27, w3c/wot-profile#125 and w3c/wot-profile#93 for extensive discussions on this topic).

6.3.8 links

"In the following examples are provide that uses different link relation values." (grammatically incorrect) -> "The examples provided below demonstrate the use of different link relation types."

6.3.9.3 response

As I suggested under section 5.3.4.3, I propose that the response member should be allowed to have an optional schema member.

6.3.9.5 Top level forms

In the case of operation type writeallproperties, it is expected that the Consumer provides all writable (non readOnly) properties and the (new) assigned values (e.g., within payload). Similarly, for the writemultipleproperties operation type, it is expected that the Consumer provides writable (non readOnly) properties. On the Thing side, Thing is expected to return readable (non writeOnly) properties in the case of readmultipleproperties and readallproperties operation types.

As with section 5.3.1, there is no information here about what the payloads of subscribeallevents, unsubscribeallevents and queryallactions operations are supposed to look like.

6.3.10 Data Schemas

Data schema serialization applies to PropertyAffordance instances, the values assigned to input and output in ActionAffordance instances, the values assigned to subscription, data, and cancellation in EventAffordance instances, and the value assigned to uriVariables in instances of Subclasses of InteractionAffordance (when a form object uses a URI Template).

Presumably this should also now mention the schemaDefinitions member of Thing.

• "The terms readOnly and writeOnly can be used signal" -> "The terms readOnly and writeOnly can be used to signal"
• "This can be used as workaround" -> "This can be used as a workaround"

6.5 Validation

This section refers to tagging of assertions into different categories for the purposes of validation. This has not yet been done but will be done prior to CR transition.

Reminder: The Editor's Note needs resolving before publication.

7.1 Semantic Annotations

• "TD Context Extensions allow for additional Vocabulary Terms to a Thing Description instance." -> "TD Context Extensions allow for the use of additional Vocabulary Terms in a Thing Description instance."
• "@type is either serialized as JSON string or as JSON array" -> "@type is either serialized as a JSON string or as a JSON array"
• "Next subsections show some sample usage" -> "The next subsections show some sample usage"

7.1.3 Example III: Gelocation Annotations

This new subsection is in work in progress. Examples will be updated based on experience of the next PlugFests.

Reminder: Issue 1 needs resolving before publication.

• "can be relied on different kind of location ontologies" -> "can rely on different location ontologies"
• "to provide static latitude and longitude metadata at Thing's top level." -> "to provide static latitude and longitude metadata at the Thing's top level."

7.2 Adding Protocol Bindings

The following TD example uses a fictional CoAP Protocol Binding, as no such Protocol Binding is available at the time of writing this specification

• I suggest this should say "no such Protocol Binding Template is available" rather than "no such Protocol Binding is available", since a "protocol binding" is defined in a Form in an instance of a Thing Description.
• Note that there is now a CoAP protocol binding template, but it is still in draft?

8.2 Data Schemas

A Thing acting as a Consumer when interacting with another target Thing described in a WoT Thing Description MUST generate data organized according to the data schemas given in the corresponding interactions

A lot of the assertions in this section use the phrase "A Thing acting as a Consumer" where I think they should just say "A Consumer". This text dates back to 1.0 but I'm not sure why it was worded this way because it reads to me like an entity which is both a Consumer and a Producer, not just a Consumer.

This language could potentially be simplified by formally defining the term "Producer" as I suggested under section 3, and referring to the two roles as "Producer" and "Consumer" rather than "Thing" and "Thing acting as a Consumer".

8.3 Protocol Bindings

A Protocol Binding is the mapping from an Interaction Affordance to concrete messages of a specific protocol such as HTTP [RFC7231], CoAP [RFC7252], or MQTT [MQTT]. Protocol Bindings of Interaction Affordances are serialized as forms as defined in § 6.3.9 forms.

I suggest adding text here to explain that a concrete protocol binding can now also be defined in a Profile. It may be helpful to distinguish between:

1. A "declarative protocol binding" provided by hypermedia forms in an instance of a Thing Description, using the vocabulary defined in a Protocol Binding Template
2. A "concrete protocol binding" provided by a Profile, which prescribes a protocol binding which all Things conforming to the Profile must use

Every form in a WoT Thing Description MUST follow the requirements of the Protocol Binding indicated by the URI scheme [RFC3986] of its href member as indicated by the Binding Templates specification at Creating a New Protocol Binding.

• "MUST follow the requirements of the Protocol Binding indicated by" -> "MUST follow the requirements of the Protocol Binding Template indicated by"

Optimally, the protocols used are listed as a scheme in the IANA registry [IANA-URI-SCHEMES]). This guarantees a unique Protocol Binding assignment. In case the desired protocol is not yet registered with IANA, it is recommended to follow the scheme value of the protocol specifications, if available. In principle, to avoid ambiguity in the identification of the protocol via the scheme, the Protocol Binding document will provide a recommended scheme value to enable unique protocol identification in the context of WoT.

It's not clear what "Protocol binding document" refers to in this note (see #1326).

8.3.1 Protocol Binding based on HTTP

See #1259 for discussion regarding whether this section should be removed, or moved to another specification.

8.3.2 Other Protocol Bindings

As with section 8.3 it might be worth mentioning Profiles here.

10. Thing Model

I'm still very unclear on the intended use cases of the Thing Model feature, how Thing Models are intended to be used by Consumers and why it needs to be part of the Thing Description specification (vs. a templating engine implemented as a software helper library).

The primary use case of defining classes of Things of which a Thing is an instance can already be achieved using semantic annotations which refer to capability schemas via a context extension, as we have been doing in WebThings for a number of years.

I'm interested to see what take-up this feature gets. Perhaps it is a better approach and we should migrate the WebThings capability schema repository to using Thing Models via links rather than a context extension via semantic annotations, but currently I'm struggling to understand the rationale for its inclusion in the Thing Description specification.

See #1078 for further discussion.

• "This paradigm can be compared with abstract class" -> "This paradigm can be compared with an abstract class"

10.2 Thing Model Declaration

• "As consequent" -> "Consequently"
• "Thing Model definitions will be also" -> "Thing Model definitions will also be"

10.3 Modelling Tools

• "specifics features are introduced" -> "specific features are introduced"

10.3.1 Versioning

• "it should be aware that this may affect" -> "this may affect"
• "In some cases it is useful to reflect a new version also in the file name" -> "In some cases it is also useful to reflect a new version in the file name"

10.3.2 Extension and Import

• "that targets to a Thing Model that is be extended" -> "that targets a Thing Model that is be extended"
• "further JSON name-value pairs from existing TD information model" -> "further JSON name-value pairs from the existing TD information model"
• "For this there exists two limitations" -> "For this there exist two limitations"
• "Those assertations preserve the semantics" -> "Those assertions preserve the semantics"
• "The tm:extends feature only allows to inherit all definitions" -> "The tm:extends feature only permits inheriting all definitions"
• "It is also allowed to override name-value pairs" -> "It is also permitted to override name-value pairs"
• "If it is intended to override an existing JSON name-value pair" -> "If the intention is to override an existing JSON name-value pair"
• "declearation" -> "declaration"
• "shows a new TM definition that overwrite" -> "shows a new TM definition that overwrites"
• "enhanced (unit)" -> "enhances (unit)"
• "the import mechanism based on tm:ref can be also used" -> "the import mechanism based on tm:ref can also be used"
• "summarizes the allowable override behavior of the extension and import TM functions" -> "summarizes the allowable override behaviour of the extension and imports TM functions"
• "Three Thing Models using the tm:ref or tm:extends feature" -> "Three Thing Models use the tm:ref or tm:extends feature"
• "The first Thing Model imports and overwrite" -> "The first Thing Model imports and overwrites"
• "Thus, such kind of Thing Model definition is not allowed." -> "Thus, such a Thing Model definition is not allowed."
• "Again, this will potential result to numeric" -> "Again, this will potentially result in numeric"
• "The new ranges of dim produce podential" -> "The new ranges of dim produce potential"

10.3.3 Composition

• "compose them to a new IoT system" -> "compose them into a new IoT system"
• "An example can be that a new Smart Ventilator should be designed which consist of two sub/child Thing Model definitions" -> "An example would be that a new Smart Ventilator is designed to consist of two sub/child Thing Model definitions"
• "Optional an instanceName can be provided" -> "Optionally an instanceName can be provided"
• "This is useful when multiple same Thing Model definitions are composed and needs to be distinguised" -> "This is useful when multiple similar Thing Model definitions are composed and needs to be distinguished"
• "A single TD can be also generated" -> "A single TD can also be generated"

10.3.4 Required

• "it is desirable to force the information which interaction model is mandatory and has to be definitely implemented in a Thing Description instance" -> "it is desirable to enforce which interaction affordances are mandatory and have to be implemented in a Thing Description instance"
• "To guarantee the implementation of particular kind of interaction models" -> "To guarantee the implementation of particular kinds of interaction models"
• "overheating is not mandatory it may be not available" -> "overheating is not mandatory it may not be available"

10.3.5 Placeholder

• "Thing Model can specify which terms should be taken in a TD instance" -> "A Thing Model can specify which terms should be used in a TD instance"
• "Placeholder can be only applied" -> "A placeholder can only be applied"
• "and the value have to be typed as JSON string" -> "and the value has to be a JSON string"
• " In the case a non string-based value of a JSON name-value pair should have a placeholder the value must be (temporary) typed as string." -> " In the case that a non string-based value of a JSON name-value pair should have a placeholder, the value must be (temporarily) typed as string."

10.4 Derivation to Thing Description Instances

• "Derivation to Thing Description Instances" (title) -> "Derivation of Thing Description Instances"
• "Thing Models can be used as template to generate Thing Description based on the restriction" -> "Thing Models can be used as templates to generate a Thing Description based on the restrictions"
• "If used, links element entry with "rel":"tm:extends" -> "If used, a links element entry with "rel":"tm:extends""
• "the required interactions MUST definitly be taken over in" -> "the required interactions MUST be taken over to"
• "If used, all placeholder" -> "If used, all placeholders"
• "security metadata details MUST be complemented" -> "security metadata details MUST be completed"
• "can carry the information which type of Thing Model is derived" -> "can carry the information regarding which type of Thing Model is derived"
• "a TD can only be an instance of only one TM at a time" -> "a TD can only be an instance of one TM at a time"
• "The links array can use the entry with "rel" : "type" maximum one. " -> "The links array can use the entry with "rel" : "type" a maximum of once."

11 IANA Considerations

It has been suggested that additional file extensions should be registered with IANA for version 1.1, see #1214.

[sebastiankb]

@benfrancis thank you very much for this detailed review and feedback.

I will start to create PRs to reflect your findings.

[sebastiankb]

The combination of this assertion and op being a mandatory member of Form causes a problem for top level WebSocket endpoints of Things which provide operations other than those listed here. See #1070 and #1192 (comment) for further discussion. I propose either lifting this constraint, or making the op member optional.

forms is mainly for interaction affordances and less for setting up init connections like to a WS endpoint. Currently the base should suffice, but I'm going with that in the future we need a general solution to initialize common protocol setup like endpoint and content type

Note that there is currently no equivalent explanation for the actions and events meta-interactions (see #1231). E.g. should the data schema of a queryallactions operation be a map of arrays, whose members follow the data schema for a queryaction operation (see #1200 (comment))? Is there an equivalent of this for events?

I think, this is not needed. It is only highlighted here that properties have a special context since it is based on the terms of the data schema class and property affordance class.

queryallactions should be more addressed in section 6.3.9 forms. Better would be to point a place in the profile spec that gives a full example.

What is the proxy-to link relation type for? I can't find a definition in the (non-normative) WoT Security and WoT Binding Template documents cited as being the source.

This coming from the Security TF. @mmccool would be cool to have more background here.

Does the "with default" assignment on the op member also mean "mandatory" if no default is provided? In particular I'm thinking about top level forms for which no defaults are defined. (See comments above about the issues with op being mandatory for Form, discussed further in #1070).

The default value table only works for ops within prop./act./ev definitions. On top level there is not such context and op should be kind of mandatory there. We need a solution for this for the CR.

[danielpeintner]

I haven't created separate issues for all the typos and grammatical errors I spotted since there are so many (you can find them all by searching for "->"),

FYI, I created a PR that covers all "->" issues, see #1335
Thanks a lot @benfrancis for all your work!

[benfrancis]

Thanks @danielpeintner!

@sebastiankb wrote:

forms is mainly for interaction affordances and less for setting up init connections like to a WS endpoint. Currently the base should suffice, but I'm going with that in the future we need a general solution to initialize common protocol setup like endpoint and content type

Unfortunately base doesn't really help since you still need to specify a subprotocol and op member as well. You still need duplicate forms for every interaction affordance, the base just makes the href member shorter, plus you can also only have one base per thing, so it doesn't help if a thing supports multiple protocols. Yes, it would be great to have a solution to this in a future version, since this creates a lot of unnecessary duplication. It isn't just about initialising a connection, it's about being able to provide a protocol binding for all interaction affordances with a single top level form.

In the meantime we will come up with a workaround for implementations in WebThings, see WebThingsIO/gateway#2882 (comment).

I think, this is not needed. It is only highlighted here that properties have a special context since it is based on the terms of the data schema class and property affordance class.
queryallactions should be more addressed in section 6.3.9 forms. Better would be to point a place in the profile spec that gives a full example.

Actually now I think about it it isn't clear what the data schema of a queryaction operation would be either. An action affordance provides an input and output data schema, but the queryaction operation may not use either (e.g. in the case of an ongoing action which doesn't yet have an output, or where the action status has its own schema).

In the example in w3c/wot-profile#91 I provide a separate data schema for the queryaction operation using a response member of the queryaction form, which is currently not valid (this relates to my comment on section 5.3.4.3 ExpectedResponse, see #1053). I used the same approach for the queryallactions operation since there's currently no definition of how to derive that data schema either.

In the Core Profile the ActionStatus data schema is provided out-of-band in the profile specification, but for implementations which don't conform with that profile it's not exactly clear to me how this should work. Should a queryaction operation use the output schema? How is the data schema of a queryallactions operation defined?

[egekorkan]

Call of 20.04:

• The feedback has already been incorporated. We will mark it as propose closing, @benfrancis please see if everything is incorporated and close the issue in that case. Regarding your last comment, I have opened another issue (Mapping of Data Schemas to operations and vice versa #1469) and we can continue the discussion there.

[benfrancis]

Thanks for all of the hard work in addressing many of the points I raised.

• "IoT" is not defined

Nit: I see that it's written in full now, but it should really be "Internet of Things", not "Internet of Thing".

The combination of this assertion and op being a mandatory member of Form causes a problem for top level WebSocket endpoints of Things which provide operations other than those listed here. See #1070 and #1192 (comment) for further discussion. I propose either lifting this constraint, or making the op member optional.

Given this hasn't been resolved I think we'll have to work around it by either using Links for WebSocket endpoints or duplicating the same WebSocket endpoint in every interaction affordance.

• What is the proxy-to link relation type for? I can't find a definition in the (non-normative) WoT Security and WoT Binding Template documents cited as being the source.

I still can't find a definition for this in WoT Security or WoT Binding. Maybe just remove this row from the table?

I suggest making it explicit that this includes action instances for all interaction affordances, i.e. not just instances of a single action affordance (see #302). Another small point, the definition of the term "queryallactions" probably shouldn't contain the term "queryallactions" (this applies to several operation types in the table).

I don't think this has been fixed, but it's a minor editorial point.

I suggest that ExpectedResponse should have a schema member of type DataSchema, like AdditionalExpectedResponse does. See #1053.

This still hasn't been addressed. From the discussion in #1341 it appears to have been postponed until 2.0. Please note that as far as I can tell this means that there's currently no way to describe the actions protocol binding from the HTTP Baseline Profile declaratively in a 1.1 Thing Description. I personally think it's OK for the concrete protocol bindings in profiles to go beyond what's possible to describe with declarative protocol bindings using protocol binding templates, but I know some people hold the view that profiles should stick to a sub-set of the features that can be described in a Thing Description, not a superset.

If this section contained a RECOMMENDATION that both the Thing Root Object and all properties, actions and events should include at least a title (and possibly a description), it would take a lot of heavy lifting away from the WoT Profile specification (see w3c/wot-profile#10, w3c/wot-profile#27, w3c/wot-profile#125 and w3c/wot-profile#93 for extensive discussions on this topic).

I don't think this was addressed but it was just a nice to have, not a blocker.

As with section 5.3.1, there is no information here about what the payloads of subscribeallevents, unsubscribeallevents and queryallactions operations are supposed to look like.

This has not been addressed. I've added a comment to #1469 to continue this discussion.

Presumably this should also now mention the schemaDefinitions member of Thing.

I don't think this was addressed but it's a minor point.

Reminder: The Editor's Note needs resolving before publication.

Still to do.

Reminder: Issue 1 needs resolving before publication.

Still to do.

• I suggest this should say "no such Protocol Binding Template is available" rather than "no such Protocol Binding is available", since a "protocol binding" is defined in a Form in an instance of a Thing Description.

Not addressed, but fairly minor.

A lot of the assertions in this section use the phrase "A Thing acting as a Consumer" where I think they should just say "A Consumer". This text dates back to 1.0 but I'm not sure why it was worded this way because it reads to me like an entity which is both a Consumer and a Producer, not just a Consumer.

Not addressed.

This language could potentially be simplified by formally defining the term "Producer" as I suggested under section 3, and referring to the two roles as "Producer" and "Consumer" rather than "Thing" and "Thing acting as a Consumer".

The term "Producer" is now defined in WoT Architecture, but no changes have been made here.

I suggest adding text here to explain that a concrete protocol binding can now also be defined in a Profile.

This wasn't addressed, which means that the Thing Description specification currently gives the impression that protocol bindings can only be serialised as Forms using protocol binding templates. This isn't strictly true as profiles can now also define protocol bindings.

It's not clear what "Protocol binding document" refers to in this note (see #1326).

Not resolved, but being discussed in #1326.

See #1259 for discussion regarding whether this section should be removed, or moved to another specification.

Not resolved, but being discussed in #1259.

t has been suggested that additional file extensions should be registered with IANA for version 1.1, see #1214.

Not resolved, but being discussed in #1214.

---

In conclusion, putting aside fairly minor proposed editorial changes, the main remaining issues are:

• Still no way to concisely describe WebSockets endpoints
• Still no way to describe an action queue
• Still no way to define schemas for some operations

Whilst these are significant missing features, I think they can mostly be worked around with either very verbose Thing Descriptions or Profiles which go beyond what is possible in a Thing Description.

It would be great to see some of the remaining editorial suggestions addressed, but otherwise I think it's safe to close this issue and continue discussion around the more major points in other issues.

[benfrancis]

Following the call for review of the latest Editor's Draft of WoT Thing Description 1.1 with a view to CR transition, I've followed up on all the points I raised in this review to see whether they've been addressed.

I think I've now filed separate issues for all of the remaining unresolved points, so I think this issue can be safely closed.

Full explanation below.

---

Nit: I see that it's written in full now, but it should really be "Internet of Things", not "Internet of Thing".

Filed #1675.

I note that the WoT Architecture document has a definition of a "Consumer", but not a "Producer".

This has now been resolved, but it isn't referenced from the Thing Description specification. I suggest adding "Producer" to the list at the start of section 3. Terminology. Filed #1668.

What is the proxy-to link relation type for? I can't find a definition in the (non-normative) WoT Security and WoT Binding Template documents cited as being the source.

I still can't find a definition for this in WoT Security or WoT Binding. Maybe just remove this row from the table?

Filed #1670.

I suggest that ExpectedResponse should have a schema member of type DataSchema, like AdditionalExpectedResponse does. See #1053.

This still hasn't been addressed. From the discussion in #1341 it appears to have been postponed until 2.0. Please note that as far as I can tell this means that there's currently no way to describe the actions protocol binding from the HTTP Baseline Profile declaratively in a 1.1 Thing Description. I personally think it's OK for the concrete protocol bindings in profiles to go beyond what's possible to describe with declarative protocol bindings using protocol binding templates, but I know some people hold the view that profiles should stick to a sub-set of the features that can be described in a Thing Description, not a superset.

This has come up again in w3c/wot-profile#259 and I still think this is a major problem for describing asynchronous actions. There is no way to define a separate data schema for an action output and the response to an invokeaction operation. I think this is sufficiently tracked by #1053 and #1665, but it's currently marked as being deferred until 2.0.

2.5 Complex Interactions is a major part of the current charter that I don't think we've delivered on in Thing Description 1.1. There are now (at risk) queryaction and cancelaction operations now which arguably provide "the ability to initiate, monitor, and cancel ongoing actions", but "support for action and event queues" has unfortunately not been achieved.

As with section 5.3.1, there is no information here about what the payloads of subscribeallevents, unsubscribeallevents and queryallactions operations are supposed to look like.

This has not been addressed. I've added a comment to #1469 to continue this discussion.

#1469 was closed but this was not fully addressed. I've filed #1665 with a more detailed review.

Reminder: The Editor's Note needs resolving before publication.
Reminder: Issue 1 needs resolving before publication.

Filed #1671.

I suggest this should say "no such Protocol Binding Template is available" rather than "no such Protocol Binding is available", since a "protocol binding" is defined in a Form in an instance of a Thing Description.

Filed #1672.

A lot of the assertions in this section use the phrase "A Thing acting as a Consumer" where I think they should just say "A Consumer". This text dates back to 1.0 but I'm not sure why it was worded this way because it reads to me like an entity which is both a Consumer and a Producer, not just a Consumer.

Filed #1673.

A Protocol Binding is the mapping from an Interaction Affordance to concrete messages of a specific protocol such as HTTP [RFC7231], CoAP [RFC7252], or MQTT [MQTT]. Protocol Bindings of Interaction Affordances are serialized as forms as defined in § 6.3.9 forms.

I suggest adding text here to explain that a concrete protocol binding can now also be defined in a Profile. It may be helpful to distinguish between:

1. A "declarative protocol binding" provided by hypermedia forms in an instance of a Thing Description, using the vocabulary defined in a Protocol Binding Template
2. A "concrete protocol binding" provided by a Profile, which prescribes a protocol binding which all Things conforming to the Profile must use

Filed #1671.

It's not clear what "Protocol binding document" refers to in this note (see #1326).

Not resolved, but being discussed in #1326.

Still not resolved, but #1326 is tagged with 1.1.

See #1259 for discussion regarding whether this section should be removed, or moved to another specification.

Not resolved, but being discussed in #1259.

Deferred to 2.0.

t has been suggested that additional file extensions should be registered with IANA for version 1.1, see #1214.

Not resolved, but being discussed in #1214.

Still not resolved, but #1214 is tagged with 1.1.

The combination of this assertion and op being a mandatory member of Form causes a problem for top level WebSocket endpoints of Things which provide operations other than those listed here. See #1070 and #1192 (comment) for further discussion. I propose either lifting this constraint, or making the op member optional.

Does the "with default" assignment on the op member also mean "mandatory" if no default is provided? In particular I'm thinking about top level forms for which no defaults are defined. (See comments above about the issues with op being mandatory for Form, discussed further in #1070).

This is being tracked in #1070 and has been deferred until 2.0.

Note that there is currently no equivalent explanation for the actions and events meta-interactions (see #1231). E.g. should the data schema of a queryallactions operation be a map of arrays, whose members follow the data schema for a queryaction operation (see #1200 (comment))? Is there an equivalent of this for events?

I've covered this in more detail in #1665.