Re: Publication of the three WoT-related FPWDs - 15 September 2017

Dear WoT WG,


Here is a review of the recently published draft of TD. The issues I 
point out are mostly editorial and easily addressed. Since I did not 
participate in the discussions so far, I'm not judging the relevance of 
the terms nor propose important additions. I focused on the internal 
consistency of the documents.


In Example 1, there is:

"outputData": {"type": "string"},

"type" is not defined in the context document, nor "string". It could be 
interpreted as:

"outputData": {"@type": "xsd:string"},

but later in the spec, a property "type" is mentioned. However, the 
property is described only after it has been used many times in 
examples. What type of value should be used with this property is not 
clear either. It is not defined in the ontology. Also, the confusion 
between "type" and "@type" is easy to make, but from reading the whole 
spec it becomes clear that "type" is not assumed to mean the same as 
"@type".


After Example 1: "announced within the endoind (SP?) structure" -> 
endoind???


Section 5.1: "a small set of vocabulary. .. this vocabulary" -> "a small 
vocabulary" or "a small set of terms"


There is a mismatch between what's in Figure 1 and what's defined in the 
context document at http://w3c.github.io/wot/w3c-wot-td-context.jsonld 
(or at https://www.w3.org/ns/td/w3c-wot-td-context.jsonld, which is the 
same):

in Fig.1              -- in context doc
=======================================
td:base               -- td:baseURI
td:DataSchema         --  NOT DEFINED
td:inputData          -- td:hasInputData
td:interaction        -- td:providesInteractionPattern
td:InteractionPattern -- td:Interaction
td:link               -- td:isAccessibleThrough
td:mediaType          -- td:hasMediaType
td:name               -- td:hasName
td:outputData         -- td:hasOutputData
td:security           -- td:implementsSecurity
td:Security           --  NOT DEFINED
td:writable           -- td:isWritable

The context document currently uses URIs in the namespace 
http://iot.linkeddata.es/def/wot# . This should be updated.

In Fig.1 again, there are some typographic inconsistencies:
  - In the class td:Thing, the doand I am not proposing uble colon is 
separated from the attribute with a space, while it's not in other classes;
  - The first colon after td:base is in red, the second is separated 
with a space, and the type is not separated with a space, as opposed to 
other attributes;
  - On the arrow from td:InteractionPattern to td:Link, the word "link" 
is in a smaller font than the other characters;
  - On the arrow from td:Property to td:DataSchema, the word "output" is 
in a smaller font than the other characters + the cardinality has an 
extra space before the double dots.

There are also many mismatches between the examples, the documentation, 
the context document and the ontology file (at 
https://www.w3.org/ns/td/td.ttl).

In the context doc, the td:base of a td:Thing and the td:href of a 
td:Link must be resources identified by a URI, while in the spec, they 
must be something of type xsd:anyURI, and in the ontology, they must be 
plain character strings.

In Sec.6.1, first table:
The description of "@context" says that the value must be 
https://w3c.github.io/wot/w3c-wot-td-context.jsonld. Then, in the text 
after the table, it says it's 
https://www.w3.org/ns/td/w3c-wot-td-context.jsonld. All examples are 
using the github file.

"Each Thing Description instance in JSON-LD MUST this context 
information embedded" -> must *have*


Some examples have keys in red, some have keys in grey.

The examples are using properties that are neither defined, declared, 
nor described anywhere. E.g., "fields", "value", "minimum", "maximum", 
"minItems", "maxItems".


Somewhere in the spec, the URIs of the vocabulary terms should be provided.


About the ontology file at https://www.w3.org/ns/td/td.ttl:
It declares prefixes that are not used: geo:, wot:, xml:, doap:, foaf:, 
prov:.
The base is set to http://iot.linkeddata.es/def/wot#.
The ontology itself is identified as http://iot.linkeddata.es/def/wot#, 
although the vann:preferredNamespaceUri is http://www.w3.org/ns/td#.
I'm not sure the license (CC-BY 4.0) is appropriate.
The dc:publisher is http://www.oeg-upm.net/, but this version of the 
ontology should be published by the W3C.
The rdfs:range of td:inputData and td:outputData should be set to 
td:DataSchema.
The rdfs:domain of td:link should be td:InteractionPattern and the 
rdfs:range should be td:Link.
The rdfs:domain of td:security should probably be td:Thing and its 
rdfs:range should be td:Security.
The range of td:base should be xsd:anyURI.
The range of td:href should be xsd:aniURI.
The property td:required, used in examples and declared in the context 
document, should be defined in the ontology.
The definition of td:name excludes the possibility to add a language tag.
td:isWritable is not used in the spec, it should be td:writable.
The use of owl:allValuesFrom instead of rdfs:range makes the ontology 
more complex (outside RDFS), harder to understand for a non specialist 
and in the case of this spec, not justified. In fact, several of them 
are redundent with existing rdfs:range. The case of owl:someValuesFrom 
is different and can be justified, but I'm not sure it is really useful.


Best,
--AZ

On 20/09/2017 07:01, Kazuyuki Ashimura wrote:
> I am pleased to announce that the Web of Things Working Group [1] has
> published the following three First Public Working Drafts:
>
> 1. Web of Things (WoT) Architecture:
> ------------------------------------
>    This version:
>      https://www.w3.org/TR/2017/WD-wot-architecture-20170914/
>    Latest published version:
>      https://www.w3.org/TR/wot-architecture/
>    Latest editor's draft:
>      https://w3c.github.io/wot-architecture/
>
>    This document describes the abstract architecture for the W3C Web of
>    Things, which consists of three initial building blocks, i.e., (1)
>    WoT Thing Description, (2) WoT Scripting API and (3) WoT Binding
>    Templates.
>
> 2. Web of Things (WoT) Thing Description:
> -----------------------------------------
>    This version:
>      https://www.w3.org/TR/2017/WD-wot-thing-description-20170914/
>    Latest published version:
>      https://www.w3.org/TR/wot-thing-description/
>    Latest editor's draft:
>      https://w3c.github.io/wot-thing-description/
>
>    This document describes a formal model and common representation for
>    a Web of Things Thing Description. A Thing Description describes the
>    metadata and interfaces of Things, where a Thing is an abstraction
>    of a physical entity that provides interactions to and participates
>    in the Web of Things.
>
> 3. Web of Things (WoT) Scripting API:
> -------------------------------------
>    This version:
>      https://www.w3.org/TR/2017/WD-wot-scripting-api-20170914/
>    Latest published version:
>      https://www.w3.org/TR/wot-scripting-api/
>    Latest editor's draft:
>      https://w3c.github.io/wot-scripting-api/
>
>    This document describes a programming interface representing the WoT
>    Interface that allows scripts run on a Thing to discover and consume
>    (retrieve) other Things and to expose Things characterized by
>    Properties, Actions and Events.
>
>
> Please contribute to those drafts using the following Issue sites on
> the group's GitHub repositories:
> - WoT Architecture: https://github.com/w3c/wot-architecture/issues
> - WoT Thing Description: https://github.com/w3c/wot-thing-description/issues
> - WoT Scripting API: https://github.com/w3c/wot-scripting-api/issues
>
> For feedback on security and privacy considerations, please use the
> following WoT Security and Privacy Issue site, as they are
> cross-cutting over all our documents:
>    https://github.com/w3c/wot-security/issues
>
> General comments should be sent to this list <public-wot-wg@w3.org>,
> the public email list for the Web of Things Working Group.
>
> [1] https://www.w3.org/WoT/WG/
>
> Best regards,
>
> Kaz Ashimura, for the Web of Things Working Group co-Chairs
>

Received on Wednesday, 20 September 2017 08:31:17 UTC