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

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 14:30:35 UTC