Reduce or remove the constraints in section 7.2 Baseline Information Model

[benfrancis]

I suggest that section 4.1.1 Core Data Model should be removed, or merged with the main WoT Thing Description specification.

The profile should instead focus on defining constraints for the payloads of HTTP requests as part of the HTTP protocol binding.

[benfrancis]

Revisiting this issue following the First Public Working Draft.

The current draft says the goals of the WoT Core Profile are:

• guarantee interoperability among all implementations of the profile.
• limit the implementation complexity for resource constrained devices.
• ensure that a thing description is also useful for a human reader.

I do agree that defining constraints in the WoT Core Data Model section (now section 5.1) could help interoperability, limit implementation complexity and make Thing Descriptions more human readable. For example, limiting the depth of nested data structures and constraining the values of certain members (e.g. limiting units to a single ontology, though the current draft doesn't do this).

However, I find that these requirements often conflict with each other. For example, section "5.1.2.1 Mandatory Fields" sets out a list of mandatory members of a Thing Description.

Regarding the first goal, I would argue that none of these fields need to be mandatory in order to guarantee out-of-the box interoperability.

• id is not necessary if the URL of the Thing Description can be used as a fallback identifier for a thing
• title and description are not strictly needed for interoperability
• The security member may not be needed for devices which are intentionally publicly available with no authentication
• The rest of the fields are just nice-to-have additional metadata and are also not necessary for interoperability
• (Making these fields mandatory is also made largely pointless by the recommended practice in section 5.1.2.2 of providing empty strings for fields which aren't actually needed.)

Regarding the second goal, making all these members mandatory actually adds to implementation complexity.

Regarding the third goal, I agree that title and description help improve human readability, though a title can be auto-generated from the key of an interaction affordance in the worst case.

I therefore propose that:

1. If the WoT Core Data Model section is not removed then the number of mandatory fields should at least be drastically reduced (either by moving the constraints to the Thing Description specification, or removing them entirely)
2. It would be easier to meet the three defined goals if the Core Profile was split into a Core Profile and Constrained Profile (see Consider creating a Constrained Profile #59). The former could focus on human readability while the latter could focus on reducing implementation complexity.

See also: https://lists.w3.org/Archives/Public/public-wot-wg/2020Dec/0025.html

[benfrancis]

Duplicate of #3.

[benfrancis]

In retrospect I'm going to reopen this issue because #3 is specifically about "data schemas" whereas this issue is about re-evaluating the whole of the WoT Core Data Model section, including considering removing it entirely.

See also my extensive review feedback in #93 (review)

[benfrancis]

In #175, the Use Cases & Requirements of the WoT Profile specification were clarified to focus on out-of-the box interoperability, and previously discussed requirements about human readability and constrained devices were dropped.

Since #125 was closed without being resolved, I am posting here to continue the discussion about how to modify the specification to reflect that change in requirements.

To re-iterate my comments from #125, my recommendation is to remove the whole of the current section 6.2 Data Model, and instead create separate sections for:

• A constrained set of security schemes
• A constrained set of link relations (if needed)
• A constrained set of discovery mechanisms
• A very limited set of data constraints on things like time formats and units which might otherwise prevent interoperability

In my view the majority of the current constraints in 6.2 are arbitrary, unnecessarily constraining and do not contribute to the agreed goals of the specification. As a minimum this section should be marked as at risk until a consensus is reached between multiple implementers on which constraints are needed.

Examples:

• There is no need for title, description, base, id or version to be mandatory anywhere
• There is no need to constrain id to be a URN rather than anyURI
• There is no need to arbitrarily constrain the length of the title (or any) member
• There is no need to require arrays where a simple string would suffice
• There is no need to constrain the types of enums
• The recommendation to use an empty string for undefined values is undesirable
• Requirements about email addresses for developers and support are arbitrary and unnecessary
• There are valid use cases for properties without a type member (e.g. endpoints which resolve to a media file such as an image, audio or video file)
• There is no need to arbitrarily limit the depth of nested data structures
• There is no need to disallow the const keyword
• The constraint on the number of forms per interaction affordance and constraints on the values of op members are actively harmful to interoperability
• There's no need to disallow oneOf for properties
• Disallowing the use of uriVariables is actively harmful for interoperability
• There is no need to constrain the use of security fields and scopes

[benfrancis]

Another question which is yet to be answered is what a WoT Consumer should do if a Thing Description fails to validate against one of the constraints in the proposed data model. E.g. if one affordance is missing a title or description member, does it render the entire Thing Description invalid and the Consumer should stop processing it altogether and return an error?

[mlagally]

Another question which is yet to be answered is what a WoT Consumer should do if a Thing Description fails to validate against one of the constraints in the proposed data model. E.g. if one affordance is missing a title or description member, does it render the entire Thing Description invalid and the Consumer should stop processing it altogether and return an error?

That's an important question that needs careful consideration.
I carried over the discussion to #187

[mlagally]

To re-iterate my comments from #125, my recommendation is to remove the whole of the current section 6.2 Data Model, and instead create separate sections for:

• A constrained set of security schemes
• A constrained set of link relations (if needed)
• A constrained set of discovery mechanisms
• A very limited set of data constraints on things like time formats and units which might otherwise prevent interoperability

In my view the majority of the current constraints in 6.2 are arbitrary, unnecessarily constraining and do not contribute to the agreed goals of the specification. As a minimum this section should be marked as at risk until a consensus is reached between multiple implementers on which constraints are needed.

I agree that we have to align and get consensus on these points first and then do a significant rewrite. I added the length and size constraints to the agenda of today's (18.5.) call and will carry them over to next week. It would be ideal if we can have a live conversation in the next call to get consensus quickly.

[benfrancis]

I've renamed this issue to reflect the latest name of this section.

Some of the constraints have also now appear to have been moved out into separate sections:

• 6.1 Common Rules
• 7.2 Security Schemas

[mlagally]

The information model section has been removed, suggest we close this issue.