Properties, actions and events

[benfrancis]

As per the discussion on the working group mailing list I'd like to propose replacing the interactions member of the Web Thing Description with top level properties, actions and events members.

This conclusion has been arrived at separately in the draft Mozilla member submission and Dave Raggett's simplied JSON mapping proposal and helps make the description format more explicit and readable.

For example...

{
  "@context": ["http://w3c.github.io/wot/w3c-wot-td-context.jsonld"],
  "@type": "Thing",
  "name": "MyTemperatureThing",
  "interactions": [
    {
      "@type": ["Property"],
      "name": "temperature",
      "outputData": {"valueType": { "type": "number" }},
      "writable": false,
      "links": [{
        "href" : "coap://mytemp.example.com:5683/temp",
        "mediaType": "application/json"
        }]
    }
  ]
}

...would become...

{
  "@context": "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
  "@type": "Thing",
  "name": "My Temperature Thing",
  "properties": {
    "temperature": {
      "type": "number",
      "unit": "celcius",
      "writable": false,
      "href": "https://mytemp.example.com:5683/temp"
    }
  }
}

A more complex example...

{
  "@context": [
    "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
    { "actuator": "http://example.org/actuator#" }
  ],
  "@type": "Thing",
  "name": "MyLEDThing",
  "interactions": [
    {
      "@type": ["Property","actuator:onOffStatus"],
      "name": "status",
      "outputData": {"valueType": { "type": "boolean" }},
      "writable": true,
      "links": [{
        "href" : "pwr", 
        "mediaType": "application/exi" 
      },
      {
        "href" : "http://mytemp.example.com:8080/status",
        "mediaType": "application/json"
      }]
    },
    {
      "@type": ["Action","actuator:fadeIn"],
      "name": "fadeIn",
      "inputData": {
        "valueType": { "type": "integer" },
        "actuator:unit": "actuator:ms"
      },
      "links": [{
        "href" : "in", 
        "mediaType": "application/exi" 
      },
      {
        "href" : "http://mytemp.example.com:8080/in",
        "mediaType": "application/json"
      }]    },
    {
      "@type": ["Action","actuator:fadeOut"],
      "name": "fadeOut",
      "inputData": {
        "valueType": { "type": "integer" },
        "actuator:unit": "actuator:ms"
      },
      "links": [{
        "href" : "out", 
        "mediaType": "application/exi" 
      },
      {
        "href" : "http://mytemp.example.com:8080/out",
        "mediaType": "application/json"
      }]    },
    {
      "@type": ["Event","actuator:alert"],
      "name": "criticalCondition",
      "outputData": {"valueType": { "type": "string" }},
      "links": [{
              "href" : "ev",
              "mediaType": "application/exi"
            }]    }
  ]
}

...would become...

{
  "@context": "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
  "@type": "Thing",
  "name": "My LED Thing",
  "properties: {
    "on": {
      "type": "boolean",
      "writable": true,
      "href": "https://mytemp.example.com:8080/properties/on"
    }
  },
  actions: {
    "fadeIn": {
      "inputData": {
        "duration": {
          "type": "number",
          "unit": "ms"
        }
      }
    },
    "fadeOut": {
      "inputData": {
        "duration": {
          "type": "number",
          "unit": "ms"
        }
      }
    }
  },
  events: {
    "criticalCondition": {
      "outputData": {
        "type": "string"
      }
    }
  },
  "links": {
    "properties": "https://mytemp.example.com:8080/properties",
    "actions": "https://mytemp.example.com:8080/actions",
    "events": "https://mytemp.example.com:8080/events"
  }
}

The @type of an interaction is not needed as it is one of property, action or event as defined by the member name.

There are some other simplifications mixed in here which can be discussed separately if preferred:

• The type of a property, inputData item or outputData item is one of a predefined set of primitive types (recommend borrowing the primitive types from JSON Schema ).
• The links member of a property is replaced with a simple href string. If the root Thing Description resource is in JSON then the linked resources are also assumed to be in JSON. Alternative available encodings can be referenced in HTTP Link headers with an alternate link relation and a client can express a preference for an alternative encoding using HTTP content negotiation. This removes complexity from the description format and moves it into the protocol layer using the existing link relation mechanism.
• This example also includes a links member at the end with links to an actions resource providing a list of requested actions (and to which new actions requests can be POSTed) and an events resource providing a list of emitted events. This becomes more relevant when the Web Thing Description is used to describe the Thing's REST API, which again may be a separate discussion.

[draggett]

On 13 Jul 2017, at 17:12, Ben Francis notifications@github.com wrote:

As per the discussion https://lists.w3.org/Archives/Public/public-wot-wg/2017Jul/0005.html on the working group mailing list I'd like to propose replacing the interactions member of the Web Thing Description with top level properties, actions and events members.

This conclusion has been arrived at separately in the draft Mozilla member submission http://iot.mozilla.org/wot/#web-thing-description and Dave Raggett's simplied JSON mapping https://github.com/w3c/wot/blob/master/proposals/dsr-td/json-to-ld-dsr.md proposal and helps make the description format more explicit and readable.

A more complex example...

{ "@context": [ "http://w3c.github.io/wot/w3c-wot-td-context.jsonld", { "actuator": "http://example.org/actuator#" } ], "@type": "Thing", "name": "MyLEDThing", "interactions": [ { "@type": ["Property","actuator:onOffStatus"], "name": "status", "outputData": {"valueType": { "type": "boolean" }}, "writable": true, "links": [{ "href" : "pwr", "mediaType": "application/exi" }, { "href" : "http://mytemp.example.com:8080/status", "mediaType": "application/json" }] }, { "@type": ["Action","actuator:fadeIn"], "name": "fadeIn", "inputData": { "valueType": { "type": "integer" }, "actuator:unit": "actuator:ms" }, "links": [{ "href" : "in", "mediaType": "application/exi" }, { "href" : "http://mytemp.example.com:8080/in", "mediaType": "application/json" }] }, { "@type": ["Action","actuator:fadeOut"], "name": "fadeOut", "inputData": { "valueType": { "type": "integer" }, "actuator:unit": "actuator:ms" }, "links": [{ "href" : "out", "mediaType": "application/exi" }, { "href" : "http://mytemp.example.com:8080/out", "mediaType": "application/json" }] }, { "@type": ["Event","actuator:alert"], "name": "criticalCondition", "outputData": {"valueType": { "type": "string" }}, "links": [{ "href" : "ev", "mediaType": "application/exi" }] } ] } ...would become...

{ "@context": "http://w3c.github.io/wot/w3c-wot-td-context.jsonld", "@type": "Thing", "name": "My LED Thing", "properties: { "on": { "type": "boolean", "writable": true, "href": "https://mytemp.example.com:8080/properties/on" } }, actions: { "fadeIn": { "inputData": { "duration": { "type": "number", "unit": "ms" } } }, "fadeOut": { "inputData": { "duration": { "type": "number", "unit": "ms" } } } }, events: { "criticalCondition": { "outputData": { "type": "string" } } }, "links": { "properties": "https://mytemp.example.com:8080/properties", "actions": "https://mytemp.example.com:8080/actions", "events": "https://mytemp.example.com:8080/events" } } That could be further simplified to:

{ "name": "My LED Thing”, “types”: { “duration”: { "type": "number", "unit": "ms" } }, "properties: { "on": "boolean" }, actions: { "fadeIn": { “request”: { “duration”: “duration” } }, "fadeOut": { “request": { “duration”: “duration” } } }, events: { "criticalCondition": "string" }, }

Where the @type: “thing” is omitted as it is the default for a thing and implied by the media type for a thing description. The same applies to the default context.

I have define the duration type once and referred to it by name for both actions. Note that JSON Schema supports this via local links to shared schema so that a single definition can be referred to rather than duplicated in place.

I’ve used “on”: “boolean” as syntactic sugar for:

“on”: { “type”: “boolean" }

If the name in a name/value pair is interpreted as a label, and its value is a string, then apply the above macro.

In principle, this could be extended to action requests and responses that only carry a single value, e.g.

“request”: “duration” as syntactic sugar for:

“request”: { “duration”: “duration” }

Which given the type definition is itself syntactic sugar for:

“request”: { “duration”: { “type”: “number”, “unit”: “ms" } }

Note that I’ve used “request” in place of “inputData” on the basis that actions are asynchronous, and I expect that most developers would prefer request and response as terms for the action's request and response.

Finally, I omitted the communications metadata on the assumption that it is passed separately when the thing is registered, as this means that the same thing description can be used in all situations.

You would still need the communication metadata, and this could be passed to the registration API as JSON. The amount of such metadata could be minimised through the use of driver specific defaults. For a REST API, you could specify the root URI for accessing a thing, and assume that the path for a given property etc. is formed by concatenating the property name. Likewise, the driver could use the default REST Method, e.g. GET for requesting the thing’s state, and PUT for updating it.

If you need to override the default URI for a given property, this could be selected using a path string constructed from the path names, inserting “/“ for each level of sub-properties.

The simpler we can make the representations, the easier it will be for application developers.

As before, this reflects my personal ideas and should not taken as reflecting those of the WoT WG nor of W3C.

Dave Raggett dsr@w3.org http://www.w3.org/People/Raggett W3C champion for the Web of things

[mkovatsc]

As mentioned in my e-mail, this is unfortunately not how JSON-LD works. If you use standard tooling for your example

{
  "@type": "Thing",
  "actions": {
    "fadeIn": {
      "inputData": {
        "duration": {
          "type": "number",
          "unit": "ms"
} } } } }

you will receive

_:b0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/td#Thing> .
_:b0 <http://www.w3.org/ns/td#hasAction> _:b1 .

Note that all information about fadeIn is gone (thanks @vcharpenay for running the toolchain). I hope you can see the problem.

This gets a bit better with JSON-LD 1.1, but it is not a referable standard.

As said in my mail, this can of course be fixed by custom serialization with parser/serializer and converter to triples (what Dave has been working on), but this would significantly exceed the current scope. We need to get the core model done first.

A topic to collaborate could be that you work on this custom format and tooling to convert between a JSON representation and the formal core model of TD. We aim at rechartering the WG after the first set of recommendations to new building blocks such as your intended TD serialization.

[mkovatsc]

Also see https://github.com/w3c/wot/issues/259 and https://github.com/json-ld/json-ld.org/issues/430

[benfrancis]

@draggett

Where the @type: “thing” is omitted as it is the default for a thing and implied by the media type for a thing description. The same applies to the default context.

I like that.

I have define the duration type once and referred to it by name for both actions. Note that JSON Schema supports this via local links to shared schema so that a single definition can be referred to rather than duplicated in place.

I don't have strong opinions about this, but I am aware of this JSON Schema feature and I can see how it could be useful to re-use and build on type metadata in complex examples.

Note that I’ve used “request” in place of “inputData” on the basis that actions are asynchronous, and I expect that most developers would prefer request and response as terms for the action's request and response.

I don't have a strong opinion about this either, I was just copying the existing terminology from the W3C draft.

Finally, I omitted the communications metadata on the assumption that it is passed separately when the thing is registered, as this means that the same thing description can be used in all situations.

As I mentioned by email, I don't see the links in the Web Thing Description as "communication metadata", but rather links to resources which represent the Web Thing (e.g. property URLs and REST/WebSocket API endpoints). This is what makes it a description of a "web thing" vs. just a description of a "thing", which would be pretty useless on its own.

For a REST API, you could specify the root URI for accessing a thing, and assume that the path for a given property etc. is formed by concatenating the property name.

I feel quite strongly that the specification should not mandate any particular URL structure. Web developers should be able to structure their URL design however they want to and just include links to resources in the Web Thing Description.

[benfrancis]

@mkovatsc

As mentioned in my e-mail, this is unfortunately not how JSON-LD works.

I admit I did naively hope that a plain JSON description format could just seamlessly be extended with JSON-LD syntax, but you seem to be saying that would result in invalid JSON-LD.

These are the kinds of unnecessary constraints I worry the overly broad scope of the Working Group Charter is putting on the core deliverable of the Thing Description format.

As said in my mail, this can of course be fixed by custom serialization with parser/serializer and converter to triples (what Dave has been working on), but this would significantly exceed the current scope. We need to get the core model done first.

Then sadly I think the charter has this the wrong way around :(

[benfrancis]

@mkovatsc

The latest JSON-LD draft specification says "The syntax is designed to easily integrate into deployed systems that already use JSON, and provides a smooth upgrade path from JSON to JSON-LD."

This doesn't feel like the case from what you describe. What are the differences between JSON-LD 1.0 and 1.1 that you're referring to? Will version 1.1 solve this problem?

[draggett]

On 19 Jul 2017, at 16:45, Ben Francis notifications@github.com wrote: @draggett https://github.com/draggett Finally, I omitted the communications metadata on the assumption that it is passed separately when the thing is registered, as this means that the same thing description can be used in all situations.

As I mentioned by email, I don't see the links in the Web Thing Description as "communication metadata", but rather links to resources which represent the Web Thing (e.g. property URLs and REST/WebSocket API endpoints). This is what makes it a description of a "web thing" vs. just a description of a "thing", which would be pretty useless on its own.

For a REST API, you could specify the root URI for accessing a thing, and assume that the path for a given property etc. is formed by concatenating the property name.

I feel quite strongly that the specification should not mandate any particular URL structure. Web developers should be able to structure their URL design however they want to and just include links to resources in the Web Thing Description.

I agree, but having sensible defaults would reduce the effort on behalf of the Web developer.

The choice of an HTTP REST API is about the communications protocol and patterns, so I respectfully differ with you in believing that details needed for the REST API (the URI for the resource) really is communications metadata, and refers to the requirements of the message transport layer. If we include this in the same file as the interaction model, we would need to change it when registering a thing as a cloud proxy that acts on behalf of a thing hosted behind the firewall.

There is a lot of interest in REST APIs in the WoT IG/WG, but the Web of Things is intended to complement a very broad range of IoT standards, so we can’t require REST for all contexts.

P.s. one challenge I ran across in my NodeJS implementation was how to identify when a thing description refers to a local thing. This arises when an app wants to instantiate a thing given the URI for its description. It also occurs when a thing description includes references to other things. The URI could be for a DNS domain on the Internet, an IP address on the Internet, an IP address on the LAN, a DNS .local domain and so forth. A device may have several network interfaces with different IP addresses in addition to 127.0.0.1. These IP addresses may change over time, e.g. when using ARP and DHCP. This makes the role of the thing description URI as an identifier a little challenging. My code had to query the set of network interfaces, but that isn’t a full solution.

Dave Raggett dsr@w3.org http://www.w3.org/People/Raggett W3C champion for the Web of things

[benfrancis]

The choice of an HTTP REST API is about the communications protocol and patterns, so I respectfully differ with you in believing that details needed for the REST API (the URI for the resource) really is communications metadata, and refers to the requirements of the message transport layer.

Surely by definition the resources provided by a "web thing" must have URLs on the web.

The way that you describe the web thing description is as an abstract description of an "interaction model", with "communications metadata" provided separately to describe how to interact with it.

The way that I see a web thing description is as a machine readable representation of a web thing which provides metadata and links to the thing's resources on the web. This is analogous to the way a web app manifest provides metadata and links to the resources of a web app.

Can you provide an example of a web thing which doesn't have URLs on the web, and explain why it should still be described as a "web thing"? If not, then why shouldn't the URLs of a web thing's resources be included in the web thing description?

I note that that URLs are included in the thing descriptions in the current W3C WoT Thing Description draft, the Web Thing Model member submission, the OIC core specification and the OGC SensorThings API - not to mention the numerous proprietary IoT web APIs like Weave, HomeKit, Nest API, Azure IoT, AWS IoT etc.

If we include this in the same file as the interaction model, we would need to change it when registering a thing as a cloud proxy that acts on behalf of a thing hosted behind the firewall.

I don't see this as a problem. Whether the web thing is a proxy for another web thing should be irrelevant to the consumer of the Thing Description, all it needs to know is the URLs to use to reference its resources.

There is a lot of interest in REST APIs in the WoT IG/WG, but the Web of Things is intended to complement a very broad range of IoT standards, so we can’t require REST for all contexts.

I think there would be a lot of benefits to standardising on REST + WebSockets, where REST can use CoAP, HTTP/2 or any other future web application protocol. But regardless of whether it follows a REST pattern, the resources provided by a web thing must by definition have URLs on the web.

[draggett]

I think there would be a lot of benefits to standardising on REST + WebSockets, where REST can use CoAP, HTTP/2 or any other future web application protocol. But regardless of whether it follows a REST pattern, the resources provided by a web thing must by definition have URLs on the web.

I agree with the first part. The second part defines the term "web thing" as a thing on the Internet. However, app developers should be able to script things in the same way regardless of whether the devices are local or remote. For a home hub, IoT devices in the home may involve a variety of protocols (e.g. Bluetooth and ZigBee), so we need to keep this as simple as possible. Moreover, you wouldn't want to expose all things on the Internet, so some things won't have Internet URIs.

[benfrancis]

I agree with the first part. The second part defines the term "web thing" as a thing on the Internet.

Not the Internet, the web. Meaning HTTP or CoAP, not MQTT or AMQP for example.

However, app developers should be able to script things in the same way regardless of whether the devices are local or remote. For a home hub,

Sure, you can create a local "web of things" in the same way you can have an Intranet with web pages that aren't exposed to the Internet. But a connected device isn't an IoT device if it isn't connected to the Internet, neither is it technically a WoT device if it isn't connected to the World Wide Web, with a globally unique URL.

IoT devices in the home may involve a variety of protocols (e.g. Bluetooth and ZigBee), so we need to keep this as simple as possible. Moreover, you wouldn't want to expose all things on the Internet, so some things won't have Internet URIs.

A device which uses PAN protocols like Bluetooth or ZigBee is not a WoT device unless it is bridged to the web using a web protocol. It is simply a connected device.

It seems like most of the work in this working group could be drastically simplified and move a lot faster if there was a clearer definition of what the Web of Things actually is.

If you want to create an abstract data model and data formats for connected devices that can use non-web and non-Internet protocols as well as web protocols then maybe you should find another name for that activity?

[benfrancis]

I can't believe I'm writing this to Dave Raggett of all people, but here is a link to a resource on the World Wide Web, about the World Wide Web, relevant to this discussion https://www.w3.org/Help/#webinternet

I almost feel like you're trolling me Dave ;)

[draggett]

I almost feel like you're trolling me Dave ;)

Very droll! But you are right to ask the question about what is the Web in the Web of Things. For me the Web of Things is primarily about an abstraction layer that builds upon Tim Berners-Lee's vision of the Web architecture in respect to addressing, formats and protocols, particularly in relation to machine interpretable descriptions as a basis for decoupling apps from the underlying standards, so that W3C adds value to, rather than competing with IoT standards development organisations. The core Web architecture thus maps to URIs for thing descriptions, formats for those descriptions, and a heterogeneous set of protocols. The links between things corresponds to the hypertext links between pages in the Web of pages.

[benfrancis]

Very droll! But you are right to ask the question about what is the Web in the Web of Things. For me the Web of Things is primarily about an abstraction layer that builds upon Tim Berners-Lee's vision of the Web architecture in respect to addressing, formats and protocols, particularly in relation to machine interpretable descriptions as a basis for decoupling apps from the underlying standards, so that W3C adds value to, rather than competing with IoT standards development organisations. The core Web architecture thus maps to URIs for thing descriptions, formats for those descriptions, and a heterogeneous set of protocols. The links between things corresponds to the hypertext links between pages in the Web of pages.

That sounds right. I would summarise that as "giving things URLs on the Web".

Perhaps our debate here boils down to whether:

1. A web thing has just one URL which resolves to a machine readable description of an abstract interaction model, with a separate mechanism used to register a communications protocol (which may or may not be the web) with which to interact with it
2. A web thing has a root URL which resolves to a machine readable description linking to other web resources which represent the properties, actions and events of a thing, where the communications mechanism to interact with the thing is always the web itself (i.e. HTTP/WebSockets/CoAP). Any underlying non-web protocol is just an implementation detail of the layer beneath.

Or to follow the analogy of the web of pages: whether a Web Thing is equivalent to a single web page, or to a web site which has an index page linking to many other web pages.

I suppose I see a Web Thing as providing a web service which consists of multiple web resources. Those resources just happen to be representing properties, actions and events of a thing in the real world.

[draggett]

I think (2) is a specialisation of (1). Applications don't care since they interact with a local object in the same execution space and which is generated by the app platform from the thing description. This object hides the protocols. Any REST URIs for properties, actions and events belong to a layer below that of the object model, as these URIs relate to the requirements of the associated protocol. If you're using WebSockets, it is reasonable to use some form of path identifier as part of the messages, but these are not URIs.

Regardless of terminology, I think we agree on the value of JSON for thing descriptions and many of the details, and very much hope that Mozilla will actively participate in drafting the corresponding standard. Would you be interested in being one of the editors for this?

[benfrancis]

I think (2) is a specialisation of (1). Applications don't care since they interact with a local object in the same execution space and which is generated by the app platform from the thing description. This object hides the protocols. Any REST URIs for properties, actions and events belong to a layer below that of the object model, as these URIs relate to the requirements of the associated protocol.

I guess I have trouble believing that this is the way commercial WoT devices will actually work in practice, and in imagining a programming language-agnostic scripting API being the standard interface for interacting with Web Things, rather than URLs and web protocols. I've seen lots of existing examples in production of the REST + PubSub approach to IoT I'm advocating for which can form a basis for standardisation, and none at all for the one you're describing here.

Given past experience I think making the URL the standard interface for the Web of Things and defining a standard REST API is the right level of abstraction for standardisation and is much more likely to succeed.

If you're using WebSockets, it is reasonable to use some form of path identifier as part of the messages, but these are not URIs.

I do agree that a WebSockets API is stretching the definition of "web" a little. It's only the web in the sense that an HTTP GET request is upgraded to a persistent socket which is a low level interface over which a custom messaging protocol then has to be used. In Mozilla's proposal we've tried to make the WebSocket API as consistent as possible with the REST API by using the same JSON formatting for messages, but it's not as much of a natural extension of the REST API as I would like.

That's why CoAP is interesting because the NOTIFY method is potentially a much more natural extension to REST than WebSockets is to solve the PubSub type use cases. This is where I think more work needs to be done at the web protocol level, maybe at the IETF, to look at whether HTTP or HTTP/2 are good enough for IoT use cases or whether something new needs to be defined which includes a PubSub mechanism and maybe also addresses some of the security issues we're bumping into.

Regardless of terminology, I think we agree on the value of JSON for thing descriptions and many of the details, and very much hope that Mozilla will actively participate in drafting the corresponding standard. Would you be interested in being one of the editors for this?

I agree, and yes I would, but I'm not yet sure what form this collaboration could take. If the Working Group is sticking to its deliverables of defining an abstract data model based on RDF and a programming language agnostic scripting API then that's not much use to us in our WoT work at Mozilla. I expect it will take many years until this produces anything concrete enough to be useable, if ever.

I'm tempted to suggest a new WoT Interest Group activity to try to define a default JSON encoding and default REST + WebSockets API which applies those abstract principles in a concrete form. However, I'm concerned about the constraints of trying to be compliant with an in-progress RDF based data model and a standard scripting API which I don't even think are actually necessary in order to create something useable.

If the changes like the ones I'm proposing in this GitHub issue can not be applied directly to the existing Working Group Thing Description deliverable, then do you think a separate effort to define a concrete data format and API could fit within the current Interest Group Charter? Or should I look to create a new W3C Community Group for this effort instead?

We have already been approached by people at other big organisations who are interested in pursuing the concrete approach we have proposed. I would prefer not to fragment this effort if possible and at least create something which complements the current work, but I think there are clearly diverging needs here which were not adequately resolved in the process of creating the current Working Group charter.

[draggett]

At this point we need to hear from other members of the Web of Things IG/WG. I personally believe that indeed it would be appropriate to draft a specification around JSON and default protocol bindings as you suggest. I am confident that we could align this with the work item on the Linked Data vocabulary given that the data types needed are essentially those built into JSON. If others agree, it would be valuable to get a better understanding of the datatypes you're interested in, and some representative use cases.

[danielpeintner]

Hi,

I do have difficulties to follow the arguments that have been made about the current thing description proposal being less explicit and less readable as the plain JSON proposal.

Correct, the plain JSON proposal might be slightliy more compact.

Having said that, the current TD (based on JSON-LD) gives you all the tools built around JSON-LD and linked data for free. The new JSON format does not do that. Why should I give up this huge capabilities? Just because it is slightly less compact.

I wonder who is going to built all those tools and toolings that are missing in a proven manner?

Moreover, I can also understand that some use-cases might not need this additional power. But I think it does not hurt either. Parsing and processing one or the other format with a plain JSON parser seems to work likewise.

What else is a real blocking point?

My two cents

[draggett]

The translation to Linked Data from JSON is easy with a small script, and there is plenty of tooling around Linked Data. However, that is not the point as most Web developers are suspicious of Linked Data and prefer simple use of JSON. We want to win over Web companies to support the Web of Things, and hence we should be motivated to reach out to Web developers and make it as easy and appealing for them as possible.

[benfrancis]

@danielpeintner I think it's an issue of balancing technical capabilities with developer usability.

At Mozilla we would like to turn web developers into WoT developers by re-using existing proven technologies from the web of pages in the web of things. Experience tells us that most web developers are put off by semantic web technologies which can appear very complex for simple use cases.

This is why I would personally like to see a simple but extensible description format for describing web things along similar lines to the W3C Web App Manifest format for describing web apps.

My ideal would be a plain JSON based format (denoted by a Web Thing Description MIME type) with an implied default context and a simple built-in vocabulary (so no need for @context or @type definitions for simple use cases), but which can still be extended with semantic markup for more complex use cases.

What is it that prevents the above JSON examples being interpreted as JSON-LD (as opposed to being converted from one format to the other as @draggett describes)? What changes would need to be made to make this possible?

[benfrancis]

Also, is the answer different for JSON-LD 1.0 vs. JSON-LD 1.1?

[benfrancis]

Let's take an even simpler example...

{
  "name": "My On/Off Switch",
  "type": "onOffSwitch",
  "properties": {
    "on": {
      "type": "boolean",
      "href": "https://mythingserver.com/things/onoff1/properties/on"
    }
  }
}

What prevents this being interpreted as JSON-LD if the context is specified elsewhere?

[draggett]

If the context is available it is easy to translate to both JSON-LD and to Turtle. It took me just a few hours to write a simple JavaScript library for this.

[vcharpenay]

@benfrancis

I've seen lots of existing examples in production of the REST + PubSub approach to IoT I'm advocating for which can form a basis for standardisation, and none at all for the one you're describing here.

In theory, nothing prevents you from implementing a RESTful interface over MQTT. In fact, I have seen this at Siemens. On the one hand, handling resources from a programmer perspective is simple and on the other hand, it allows for asynchronous request/response exchanges in highly distributed systems.

But that was a minor comment. I wanted to answer your question about JSON-LD. As @mkovatsc explained, you can always interpret JSON as JSON-LD but what matters is the RDF triples you get as a result (otherwise, why would you do that?). If I take your simple example, I only get:

_:b0 <http://iot.linkeddata.es/def/wot#name> "My On/Off Switch" .

From this, I can not even infer whether _:b0 is a Thing or a Property/Action/Event...

The reason why the rest of the object gets lost is that RDF and JSON have quite different information models and JSON-LD (1.0) had to make assumptions. One assumption is that RDF triples (subject, predicate, object) should map to JSON as follows: { @id: subject, predicate: object }. JSON keys must be predicates. In your example, this does not fit because some keys implicitly map to objects. Here is a JSON object that includes the same information as in your example and yields the correct triples:

{
  "name": "My On/Off Switch",
  "type": "onOffSwitch",
  "properties": [
    {
      "@id": "on",
      "type": "boolean",
      "href": "https://mythingserver.com/things/onoff1/properties/on"
    }
  ]
}

The structural difference between your JSON and mine is subtle, as you can see. One way to look at it is that the structure you propose is syntactic sugar compared to the JSON-LD version. Syntactic sugar is important (Python's success is a good example) and I am not against having two distinct JSON formats for the Thing Description. However, I would still use JSON-LD as a canonical representation for Thing Descriptions, as it is more expressive than plain JSON.

As a developer, if you want to interpret your TD as RDF triples, you would just have to transform the properties map into an array and then use the standard JSON-LD processing algorithms. The transformation is trivial:

let td = { /* your example */ };
let other = JSON.parse(JSON.stringify(td));
other.properties = [];
for (var k in td.properties) {
  let p = td.properties[k];
  p['@id'] = k;
  other.properties.push(p);
}

In fact, since this pattern is very common, I proposed a change in JSON-LD: json-ld/json-ld.org#430. One can specify in the JSON-LD context that the properties map is a container for @id, in which case your example and mine are equivalent. The proposal has been adopted in JSON-LD 1.1.

[benfrancis]

@vcharpenay Thanks for this clear explanation.

In fact, since this pattern is very common, I proposed a change in JSON-LD: json-ld/json-ld.org#430. One can specify in the JSON-LD context that the properties map is a container for @id, in which case your example and mine are equivalent. The proposal has been adopted in JSON-LD 1.1.

To make sure I understand correctly, are you saying that with a separately defined JSON-LD 1.1 context which uses the new feature you describe, it would be possible to interpret the example I gave as JSON-LD without losing data?

So something along the lines of...

JSON-LD Web Thing Context

{
  "@context": {
    "schema": "http://iot.schema.org",
    "name": "schema:name",
    "type": "schema:type",
    "properties": {
      "@id": "schema:property",
      "@container": "@id"
    }
  }
}

JSON Web Thing Description

{
  "name": "My On/Off Switch",
  "type": "onOffSwitch",
  "properties": {
    "on": "boolean"
  }
}

...where the context for the Web Thing Description is denoted by a link relation or implicitly via a special MIME type.

(I'm sure I will have got some of this wrong...)

[draggett]

Assuming the thing description has the URI http://example.com/switch and a default context

 {
     "name": "My On/Off Switch",
     "type": "onOffSwitch",
     "properties": {
          "on": {
               "type": "boolean",
               "href": "https://mythingserver.com/things/onoff1/properties/on"
          }
      }
 }

then using my algorithm, this example translates to Turtle as follows:

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix td: <http://www.w3.org/ns/td#> .

<http://example.com/switch> a td:thing ;
     td:name "My On/Off Switch" ;
     td:type "onOffSwitch" ;
     td:property _:1 .
_:1 td:name "on" ;
     td:type  td:boolean ; 
     td:href  <https://mythingserver.com/things/onoff1/properties/on> .

To translate the string "onOffSwitch" into an RDF node, you would need to add an @context declaration to the JSON that defines it, since it isn't likely to be defined in the default context.

In summary, translation to RDF triples (Linked Data) is trivial using a simple algorithm, a default context, and additional context for domain specific vocabulary terms. Note that simple apps won't be interested in the triples. Smarter apps that need to adapt to variations across devices from different vendors will be interested in the semantics, and their developers will benefit from simple APIs for working with triples without having to deal with SPARQL, etc.

You can see further examples at the following page:

 https://www.w3.org/WoT/demos/td2ttl/

[sebastiankb]

I wonder if the web developer would really create the Thing Description (TD) by hand, or rather a TD-creator JS library is used in the future. As a developer, I would like to focus on the development of the Thing's properties, actions, and/or events to be offered as a service. I would be happy if a library can produce the TD in the background for me and takes also care that the content is aligned what you have defined in the source code. This is also valid for the consumer of a Thing Description. I think there will be also libraries which interprets for you the TD and provides functions which can be embedded in consumer source code then.

What I like to point out is that most likely the human will not really see or create the raw content of the TD (similar with html). So, why we should spend so much effort in a JSON to Triple mapping when we can simple use JSON-LD which meets completely the needs in WoT?

[draggett]

That sounds like the debate between binary protocol definitions (ASN.1) and text based protocols (most of the IETF protocols). Having an easy to read format is a big plus and simplifies debugging as well as manual authoring. People love view source for HTML pages and find comfort in being able to write HTML tags by hand even if most of the time they rely on libraries. Making the Web of Things easy and appealing to Web developers is very likely to be critical to its wide spread adoption as a Web standard.

[sebastiankb]

That sounds like the debate between binary protocol definitions (ASN.1) and text based protocols (most of the IETF protocols).

Not really. I just compare JSON-LD vs JSON and not binary vs. text.

Having an easy to read format is a big plus and simplifies debugging as well as manual authoring.

Yes, this is what everybody supports in the group. However, the one does not preclude the other. A rich tool and library support is also very important for a wide spread adoption, right?

Making the Web of Things easy and appealing to Web developers

Is this still true when we have to setup a n+1 standard and new libraries and tools has to be developed (also see @danielpeintner comment above)?

[draggett]

We shouldn't mandate a single serialisation format, so yes, we can have JSON-LD for those who want it and JSON as a more appealing option for the vast numbers of Web developers.

Making the Web of Things easy and appealing to Web developers is critical to the success of the Web of Things as a global standard like HTML, something we all want to happen.

The underlying standard is that of the linked data vocabulary, and converting to triples is very simple in both cases.

[vcharpenay]

@benfrancis this is correct. By the way, if, by chance, you were willing to contribute to JSON-LD, the 1.1 spec has for now only one implementation (Ruby). To my knowledge, there is no plan for other implementations like jsonld.js and jsonld-java to be updated.

[mkovatsc]

A first step was done in Dec 2017 with this proposal. The WG is willing to return to the three different Interaction entry points to enable a single solution.

More detailed issues are now in: https://github.com/w3c/wot-thing-description/issues/84 https://github.com/w3c/wot-thing-description/issues/85 https://github.com/w3c/wot-thing-description/issues/86 https://github.com/w3c/wot-thing-description/issues/87 https://github.com/w3c/wot-thing-description/issues/88 https://github.com/w3c/wot-thing-description/issues/90