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

Sebastian,


Tomorrow, I won't be able to join. I would like to get more involved in 
the TD task force but at the moment, it's not very well compatible with 
my agenda. However, I can give more details by email if things are not 
clear in my review.


Best,
--AZ

On 21/09/2017 16:30, Kaebisch, Sebastian wrote:
> Dear Antoine,
>
> many thanks for your mail and for the detailed feedback. We will definitely take your comments into account for the next draft version. In tomorrow's TD web meeting I will give a short overview about your review. Maybe you have also time for joining? Web meeting details can be found here: https://www.w3.org/WoT/IG/wiki/WG_WoT_Thing_Description_WebConf
>
> Many thanks again!
>
> Best wishes
> Sebastian
>
>
>
>> -----Ursprüngliche Nachricht-----
>> Von: Antoine Zimmermann [mailto:antoine.zimmermann@emse.fr]
>> Gesendet: Mittwoch, 20. September 2017 10:30
>> An: public-wot-wg@w3.org
>> Betreff: 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 Thursday, 21 September 2017 19:18:33 UTC