Oracle review comments on simplified TD draft snapshot on 27.4.

[mlagally]

Oracle review comments on simplified TD draft snapshot on 27.4.

The following comments apply on a preliminary snapshot of the Thing Description spec draft as of April 27th, 2018.
https://github.com/w3c/wot-thing-description/tree/TD-JSON-LD-1.1 spec draft.
They are not exhaustive and may not be applicable to a later version of the spec.

1. Introduction

• "The default serialisation of the TD is JSON-LD" - is this still valid? What does "default serialisation" imply - does a spec conformant implementation have to implement this default serialisation? Any others? Which format is normative?
• suggest to mark up the keywords "Propert[y|ies], Action, Event" in italcs, to improve readability
• typo: toogle-> toggle
• typo: accessable
• "Events which are, e.g., unexpected or irregular" - what is an irregular or unexpected event?
• "The TD can be also processed as a RD-based model." - RDF?
• what is meant by: "default assumption vocabularies"?
• suggest to clarify terminology: vocabulary is used to denote the complete set of keywords and also an individual keyword (field).

3. Namespaces

• What is the purpose of the namespace? Where is it used?

4. Conformance

• clarify if the RFC2119 keywords MUST, MAY, ... are only normative, if they are in uppercase? Is a lower-case "must" normative?
• "In case of JSON-LD serializiation, a Thing Description instance in JSON-LD format complies with this specification if it follows the normative statements in Section 6. Serialization". What about a plain JSON serialisation?

5. Information Model

• the term "interaction patterns" is frequently used in this chapter. It would be useful to include parts of section 5.2 from the architecture document to give context.

The order of the keywords in the following sections should be changed to better reflect the conceptual structure.

5.1 Overview

This section talks about a vocabulary, whereas section 6 talks about classes. There term "vocabulary" is a bit vague, I recommend to use "classes" containing "fields" and just talk about vocabulary in the context of RDF.

5.2.1 Thing

The thing description should contain a set of additional metadata keywords to determine the manufacturer, model number, serial number, version, creation date, last modified date, ... of the TD. This allows to distinguish between different TD versions and device versions.

• "actions Keeps all Action-based ..." -> "Contains all Action-based ..."
• " ... unique URI (includes also URNs) ID of the Thing". Drop "ID". Is there a normative requirement, whether to use a URN or aq URI. Can we mix both?
• "events", "properties": "Keeps" -> "Contains"
• "links" - it would be useful to understand the motivation for the links between things. What is the application scenario? what are the semantics of a link? They are not used by any other keyword.
• "base": "... URI that is valid for all defined local interaction resources.". What does "valid" mean? used as a prefix or common entry point?
• typo: "additionel" -> "additional"
• "name": "Name of the Thing or interaction pattern "
• "support": please consider naming it "contact"

5.2.2 Property

• "Property provides readable and/or writeable data" - Objects?
• "that can be static (e.g., supported mode, rated output voltage, etc.) or dynamic ..." -> "containing constant or variable values"
• "items": "Used to defines characteristics of an array." intems contain property types in an array, however this is not part of the example. Where do arrays come in? Is this a left-over?
• "properties": unclear: why again a properties? does a property structure [recursively] contain a property section?
• typo: "constand"
• "range": type is a "Literal" - should it be 2 literals?
• typo: "itmes"
• "writable Boolean value that indicates whether a property is writable" - I would expect that the default would be writable=true

5.2.3 Actions

Is there a way to cancel an action? How does a client query the status?

• change: "actions cannot be applied instantaneously like property writes" -> "actions are always asynchronous". Is this really the case?
• "forms" : allows multiple endpoints. What happens if the same action is called via two endpoints at the same time? Is there any precedence? any limitation to "one endpoint per protocol"?
• "Usually, ongoing Actions are modelled as Task resources" - What is a task resource?
• typo: "additionel"

5.2.4 Event

• "Please note, this class also inherited all vocabulary from the InteractionPattern class." - Where is this interaction pattern class? If it was dropped, this section must contain the keywords.

5.2.5 Form

• "href" - please clarify "interaction pattern"
• "mediaType" - is there a normative minimum set of mediatypes, that has to be supported by a compliant implementation?
• "security" - semantics needs to be clarified
• typo: interacions

5.2.6 Link

See above: it would be useful to understand the motivation for the links between things. What is the application scenario? what are the semantics of a link? They are not used by any other keyword.

typo: "oeration"

5.2.7 Security

-- not reviewed --

6 Thing Description Serializations

Which of the two formats (JSON/ JSON-LD) is the default?
Which format is normatively required?

6.1 JSON

• "all defined core vocabulary as defined in Vocabulary Definitions " - please simplify the language. Does it mean that for each keyword in the classes of section 5 there is a corresponding JSON key?
• typo: "transtormed"
• "Vocabularies that are based on simple types string and anyURI MUST be serialized as JSON string." - Please improve readability, e.g. "keywords that use the simple types string and anyURI MUST be serialized as JSON strings."
• what about fields of other types, such as arrays, objects, boolean?
• "class-based types" - suggest to use the terms: "simple types" and "complex type".

6.1.1 Thing as a whole

• "Each mandatory and required vocabulary" - is there a difference between "mandatory" and "required"?
• "The type of the fields properties, actions, events, and securityDefinitions MUST be serialized as a JSON object." - is the type serialised or the value?
• "The type of the field links MUST be serialized as a JSON array." Some rationale would be nice, as to why this is different for the links.

6.1.2 properties

• several occurrences: "type of the fields ..." - IMHO the serialisation contains only values
• Example 4: "required" in this example is an array, whereas chapter 5 defines it as string. Why is required not simply a regular field of each property, such as "writable"?
• writable properties: the example should contain writable properties. What happens if there is a conflict between the access permissions of a property with sub-properties, i.e. if the property is read-only, but the sub-properties are declared writable? The spec should clarify the precedence (e.g. the parent wins)

6.1.3 actions

• "The members keys of input and output rely on the the class Property." - Please clarify what is meant here.
• "The forms field MUST NOT be serialized as a JSON object.
  The type of the field forms MUST be serialized as a JSON array." - the second sentence already gives the normative requirement, the first one can be removed.

6.1.4 events

• The semantics of the event mechanism should be defined somewhere in a normative way. Where?

6.1.5 forms

-- not reviewed --

6.2 JSON-LD 1.1

-- not reviewed --

[sebastiankb]

Michael, many thanks for your review! This helps a lot to quickly improve the new TD version.

@takuki can you take care of it? This would be great.

[sebastiankb]

"The default serialisation of the TD is JSON-LD" - is this still valid?

The sentence is now replaced by

The serialization of the TD instances is based on JSON and includes at least the TD core vocabularies as JSON keys as defined in this specification document.

[sebastiankb]

suggest to mark up the keywords "Propert[y|ies], Action, Event" in italcs, to improve readability

done

[sebastiankb]

typo: toogle-> toggle
typo: accessable

done

[sebastiankb]

"Events which are, e.g., unexpected or irregular" - what is an irregular or unexpected event?

sentence is replaced by

The WoT's Event model enables a mechanism for events to be notified by a Thing. Here, ...

[sebastiankb]

what is meant by: "default assumption vocabularies"?

This part will be replaced by

The TD specification also defines some vocabularies (writable, observable, mediaType) that have default values. If these vocabularies are not implicit in a JSON TD instance, the JSON TD processor follows the default assumption for interpretation as defined here in this specification. In terms of JSON-LD 1.1 serialization and semantic's open-world assumption these vocabularies will be always implicit present in the instances.

[sebastiankb]

What is the purpose of the namespace? Where is it used?

I changed the text in this chapter to provide more background:

The namespace for the W3C Thing Description vocabularies as defined in this document is http://www.w3.org/ns/td#. The Thing Description ontology is available at https://www.w3.org/ns/td/td.ttl and the conext file is available at https://www.w3.org/ns/td/w3c-wot-td-context.jsonld.

[sebastiankb]

clarify if the RFC2119 keywords MUST, MAY, ... are only normative, if they are in uppercase? Is a lower-case "must" normative?

This is a standard phrase as provided here https://tools.ietf.org/html/rfc2119
We should take care in the document to follow this suggestions and rewrite lower cases to upper cases if this is the case.

[sebastiankb]

"In case of JSON-LD serializiation, a Thing Description instance in JSON-LD format complies with this specification if it follows the normative statements in Section 6. Serialization". What about a plain JSON serialisation?

I made this part more abstract and simple wrote:

A Thing Description instance complies with this specification if it follows the normative statements in Section 5. Vocabulary Definition and Section 6. Thing Description Serializations regarding Thing description serializiation.

Other parts were removed

[sebastiankb]

Which of the two formats (JSON/ JSON-LD) is the default?
Which format is normatively required?

There is now a different explanation:

Thing Description instances are modeled and structured based on the Thing Description information model. Instances can be serialized in simplified form as JSON TD or in a comprehensive JSON-LD 1.1 format.

[sebastiankb]

typo: "transtormed"
done

[sebastiankb]

"Vocabularies that are based on simple types string and anyURI MUST be serialized as JSON string." - Please improve readability, e.g. "keywords that use the simple types string and anyURI MUST be serialized as JSON strings."

done

[sebastiankb]

"class-based types" - suggest to use the terms: "simple types" and "complex type".
used both complex-/class-based types

[mkovatsc]

Instances can be serialized in simplified form as JSON TD or in a comprehensive JSON-LD 1.1 format

Noooooo, no, no! :)

This is exactly what we want to avoid!

There is only one JSON-based serialization or rather representation format for TDs, which is identified by the Media Type application/td+json.

The representation format follows the rules of JSON-LD 1.1, so that serializer/parser implementations can choose between two approaches: (a) plain JSON processing with handling of the terms baked into the implementation (comparable to a SenML implementation) or (b) JSON-LD processing where a JSON-LD library is used to convert the TD serialization into an internal representation (structured data in the memory of the process handling the TD).

node-wot uses approach (a)

Thingweb Directory uses approach (b)

In fact, both approaches can decide to ignore semantic annotations. However, it is more likely that approach (a) omits the support completely or only supports specific terms relevant to the application. For instance, it could not produce any @... entries when serializing and ignore all @... entries when parsing; or only parse values of @type that it knows.

[mkovatsc]

Note that there can be other representation formats for TDs that are not JSON-based, for instance a CBOR-based format identified by application/td+cbor or an EXI-based format identified by application/td-exi if schema-informed compression or application/td+exi if generic EXI compression.

[mkovatsc]

For a full disclosure, I should probably add that a TD information model, i.e., and internal representation, can also be constructed from a JSON-LD 1.0 representation format identified by application/ld+json -- note the L instead of T. This is because we have a full semantic model with ontology. See it as a Linked Data document that contains all the information that would also be in a TD, so it can be easily converted into a TD representation, which then has the Media Type application/td+....

However, let's leave this out of the TD spec and leave it to people who know what they are doing. We might inform about this in an informal document.

[sebastiankb]

@mkovatsc

Noooooo, no, no! :)

You just describe what a parser has to do. But, how are you going to formulate/describe what is transported on the wire? There we have a JSON-LD valid format and a non JSON-LD valid format. Right?

[sebastiankb]

@mlagally

"The type of the field links MUST be serialized as a JSON array." Some rationale would be nice, as to why this is different for the links.

Good question which I also ask myself. In the previous version we defined the link as array. We should ask the group if object representation would be also ok.

[mkovatsc]

You just describe what a parser has to do. But, how are you going to formulate/describe what is transported on the wire? There we have a JSON-LD valid format and a non JSON-LD valid format. Right?

No.

On the wire are representation formats (e.g., HTML, CSS) that are identified by Media Types (e.g., text/html, text/css).

We wanted and agreed to avoid releasing different representation formats for WoT Thing Description (i.e., JSON-LD 1.0 vs JSON TD). Thus, the TD deliverable has to specify only one representation format, and the consensus was to do so, giving it the Media Type application/td+json. This format is JSON-based (cf. ...+json), but it also follows the syntax of JSON-LD (1.1) to streamline the semantic evaluation of TDs.

That means, it does not matter if the format has, for instance, an @context field or @typefields or not, they are optional fields, and the data on the wire always has the Media Type application/td+json; it is one and the same format.

[sebastiankb]

So, to conclude what we have is:

• application/td+json: is actually JSON-LD 1.1, however, can may be skip @context, @type etc.
• application/td+exi: binary JSON representation of the TD
• application/td+cbor: binary representation of the TD
• application/ld+json JSON-LD 1.0 (and JSON-LD 1.1?) serialization of the TD (identified by the @context)

[mkovatsc]

For the WoT Thing Description deliverable we have:

• application/td+json: a JSON-based format that follows the syntax of JSON-LD 1.1, but requires some minimal preprocessing before it can be fed to a JSON-LD processor: insert @context if missing, add TD context file if only domain-specific vocabulary is given in @context, make sure the processing rules are set correctly (@container for object notation), framing to add default values (observable: false).

In future deliverables we might have these two, but will not be able to define them in the current charter period:

• application/td-exi: binary representation of the TD based on EXI
• application/td+cbor: binary representation of the TD based on CBOR

An out-of-band mechanism to also convey the information of TDs in a generic way:

• application/ld+json: JSON-LD 1.0 or 1.1 depending on @version in @context -- no preprocessing and not directly compatible with WoT implementations, so you need to know what you are doing (e.g., use it to populate a knowledge base from which you can export application/td+json TDs.
• text/turtle: Turtle, which is also an RDF serialization and can contain the TD information just like generic JSON-LD
• ...

[sebastiankb]

but requires some minimal preprocessing before it can be fed to a JSON-LD processor: insert @context if missing, add TD context file if only domain-specific vocabulary is given in @context, make sure the processing rules are set correctly (@container for object notation), framing to add default values (observable: false).

This is only true for the TD instances do not fulfill the JSON-LD 1.1. rules. TD instances that already have all the @context etc, an pre-processing may be not necessary then.

[mkovatsc]

But when do you do validation then to make sure it is really a TD? This is part of this preprocessing and this is how node-wot does it.

Also, what exactly are "JSON-LD 1.1. rules"? Even if the default value issue is solved through JSON-LD 1.1 Framing, you need to apply this Framing first, that is, do preprocessing. This you can only do based on metadata, that is, the Media Type.

[mkovatsc]

Good question which I also ask myself. In the previous version we defined the link as array. We should ask the group if object representation would be also ok.

Links can either be a single value (an object with the href etc. fields) or an array of these objects. An object notation as for e.g. Actions does not make sense, because there is no clear access key. HAL tried to use rel for this, but this was not good, because rel often needs to be a (unordered) list.

[sebastiankb]

But when do you do validation then to make sure it is really a TD?

Indeed that is a pity that we not want to point out via a media type such as application/td-ld-json that the provided TD instance follows the JSON-LD 1.1. TD approach. Pre-processing can be omitted.

[sebastiankb]

An object notation as for e.g. Actions does not make sense, because there is no clear access key.

Good point

[mkovatsc]

There is still a misunderstanding of how representation formats work and of Media Types, what they give you and how you use them...

You do not need application/td-json-ld. What would you want to gain from it?

You still need to check if optional fields with default values are omitted. From application/td+json you get the information for correct framing and you know you can process it as JSON-LD given the always required preprocessing.

Also you want the sender to guess how the receiver will want to process it and then set the Media Type accordingly? You always want to offer two links for content negotiation of the same content? You want JSON only parsers to reject TDs with "application/td-json-ld" although they could parse it?

[sebastiankb]

You do not need application/td-json-ld. What would you want to gain from it?

I would expect that I get a TD that follows the (JSON-LD based) specification of the TD also including the default values etc. In that case I would submit directly the TD to JSON-LD parser to retrieve TDs content. In the case of the generic application/ld-json I'm with you to check if all needed keys are provided to make a valid TD parsing.

[mkovatsc]

But you just create a club that excludes raw JSON parsers although they could get all the information they need.

Also on the Internet you should never fully trust what a sender tells you. You never know if he really included all default values. With the preprocessing we have something more robust.

[mlagallyw]

Imho the format must be parsable by plain JSON parsers. It is difficult to mandate all "consumers" to implement the JSON-LD specification, even though they may never be able to handle semantic annotations.

[sebastiankb]

But you just create a club that excludes raw JSON parsers although they could get all the information they need.

No. JSON-LD is JSON based document that any JSON parser can handle it. In the past we followed this philosophy (such as in node-wot) and we pointed this out in the TD specification https://www.w3.org/TR/wot-thing-description/#parsing .

Also on the Internet you should never trust what a sender tells you. You never know if he really included all default values.

I know, however, there are also time critical scenarios out there where parties are trusted and a pre-processing step not necessary to save time and resources.

[sebastiankb]

Imho the format must be parsable by plain JSON parsers. It is difficult to mandate all "consumers" to implement the JSON-LD specification, even though they may never be able to handle semantic annotations.

Just to be clear. I just make the proposal to have maybe both application/td-json (no semantics keys based on JSON-LD 1.1) and application/td-ld-json (includes semantics keys based on JSON-LD 1.1).

[mkovatsc]

Just to be clear. I just make the proposal to have maybe both application/td-json (no semantics keys based on JSON-LD 1.1) and application/td-ld-json (includes semantics keys based on JSON-LD 1.1).

Exactly. And because of exactly this I am so concerned and cannot understand your intentions. This is throwing away all the consolidation work we have done between the JSON TD proposal and the previous WG draft to not counter IoT fragmentation with two separate TD solutions...

[handrews]

Just to be clear. I just make the proposal to have maybe both application/td-json (no semantics keys based on JSON-LD 1.1) and application/td-ld-json (includes semantics keys based on JSON-LD 1.1).

@sebastiankb are you intentionally making these -json instead of +json, and if so, why? The structured suffix is important.

I also generally agree with @mkovatsc and think that if there are time/resource concerns then maybe optimizing the pre-processing requirements would be a better approach?

[sebastiankb]

i had a chat with matthias and we agreed to stick with the single media type approach for now. I updated section 6 based on today's discussions.

https://w3c.github.io/wot-thing-description/#TD-serialization-section

Any feedback is welcome :-)

[sebastiankb]

The new updated TD version includes almost all suggestions. Many thanks again for your feedback.