properties, actions and events as objects using JSON-LD 1.1

[benfrancis]

Let's try and be clearer about whether and how JSON-LD 1.1 could allow properties, actions and events to be represented as objects/maps rather than arrays in the Thing Description.

An array is harder to parse and being able to refer to an individual property by a key can be very useful, i.e. thing.properties.temperature vs. thing.properties[2]

[draggett]

In addition, it is easy to iterate through property names for objects in JavaScript via a for-in statement with a test to skip JavaScript object native properties. I use this technique frequently in my JavaScript library for RDF graphs as a means to process sets.

[mkovatsc]

An array is harder to parse

This depends on your use case: When you already know which names exist or are a human who want to read a TD, objects are nicer. When you want to parse a TD to learn what names exist in the TD, an array is better. At the PlugFests, we mainly use the TD as exchange format for metadata so we can discover what other Things by other people with different naming schemes actually offer. Your example is about accessing the information, not parsing; parsing an object is actually harder.

whether and how JSON-LD 1.1 could allow properties, actions and events to be represented as objects/maps rather than arrays

Whether

Yes :)

How

JSON-LD 1.1 (at the moment) interprets the key as the @ids of the the respective object values. @id would be a unique identifier of the Interaction, and hence much clearer than name. However, the value of @id must become a valid URI following the expansion rules: the origin URI of the TD/jsonld doc or a defined @base in the @context is prefixed to the key. This can be problematic, as the URI from where the TD was fetched is not necessarily stable nor unique for the Thing described (e.g., when coming from a Thing Directory). So the @base MUST be defined or the @id marked as a blank node. When opting out of the semantic annotations (i.e., not setting @base to the Things identity) the first one cannot be done. To do the second one, the keys would need to be prefixed with _: to translate to blank nodes -- very ugly.

But

...JSON-LD 1.1 anyway will not be out before we must publish the Candidate Recommendation :(

Possible way forward

#90 opens the door for preprocessing that can be used to bridge the time until 1.1 becomes a standard and to avoid the ugly part from above (_:). I am in for that, as long as we limit it to a clear, small set of formally defined rules. It enables us to go beyond the current limitations that make the TD how it is at the moment.

Consequently, we are able to incorporate requirements from the JSON-TD proposal in the WG and first steps such as defaults are already outlined here.

As said in the beginning, for parsing a TD to learn what is offered, the object structure is actually worse. When thinking about the Scripting API for manually written (opposed to a machine-client that picks Interactions based on their semantic metadata), it seems much nicer, because thing.readProperty("temperature") can become a much better TD-aligned thing.properties.temperature.read() (note both return a Promise due to the distributed nature; an async getter with await needs still to be investigated).

[draggett]

Another way forward would be to define our own mapping from JSON to RDF following the algorithm I proposed and demonstrated, see [1]. This maps JSON object property names to RDF predicates via context declarations. The approach starts with the URL for the thing description as the subject, and maps the value of JSON object property to the object node in the associated RDF triple. RDF blank nodes are generated as needed. The algorithm allows for metadata associated with arbitrary levels of nested compound data structures. JSON object property names in the thing descriptions are mapped to metadata predicates or to named nodes alternating with the depth of the object nesting.

This approach offers use of simple familiar JSON whilst retaining the flexibility needed to support metadata associated with compound data structures for thing properties, events, action requests and responses. I understand that our colleagues from Siemens feel we should start by assuming the use of JSON-LD and JSON Schema, due to the popularity of these standards and alleged availability of associated libraries. However, doing so complicates the JSON representation of things, and risks continued market fragmentation as developers stick to simpler proprietary approaches rather than accepting what they feel is unjustified complexity. I would prefer us to be guided by requirements from the set of uses cases we deem relevant, and by keeping everything as simple as possible whilst keeping the door open for extensions to richer use cases.

[1] https://github.com/w3c/wot/tree/master/proposals/dsr-td

[mkovatsc]

Another way forward would be to define our own mapping from JSON to RDF following the algorithm

I am personally against a custom approach that ignores existing standards and has no existing extension points. Also for W3C it should be of interest not to circumvent their own standards (in this case JSON-LD).

However, doing so complicates the JSON representation of things, and risks continued market fragmentation

No! These issues are being addressed with our simplified proposal. The remaining open issues are personal preferences not facts and would occur in the same way in a JSON-only standardization track.

[benfrancis]

I'm afraid half of the semantic web jargon here and in #86 and #90 goes straight over my head. Like the vast majority of web developers I've never used semantic web technologies in production, with the exception of parsing simple linked data from web pages (like OpenGraph and Schema.org) in web browser/OS implementation.

@mkovatsc Could you please illustrate with examples what Thing Descriptions could look like using JSON-LD 1.1 and with your proposed stop-gap solution until JSON-LD 1.1 arrives? I think @draggett has already provided examples of mapping JSON to Linked Data here https://github.com/w3c/wot/blob/master/proposals/dsr-td/json-to-ld-dsr.md

[draggett]

Unlike #mkovatsc I am not convinced that the "simplified proposal" will address the full range of requirements without significant complications to the way you need to express models in JSON. As always, we should have an agreed set of use cases that can be used to compare and contrast different solutions. These need to go beyond the trivial cases to ensure that the approach we're taking isn't leading us up a blind alley.

Can you show me, for instance, how your proposal addresses the following:

• properties with sub-properties (with further sub-properties)
• the ability to associate metadata with sub-properties
• application defined named types with their own metadata
• the distinction between sorted and unsorted collections

FWIW my proposal handles that fine and is fully extensible, contrary to your claim.

[draggett]

#benfrancis wrote:

I'm afraid half of the semantic web jargon here and in #86 and #90 goes straight over my head. Like the vast majority of web developers I've never used semantic web technologies in production, with the exception of parsing simple linked data from web pages (like OpenGraph and Schema.org) in web browser/OS implementation.

Semantic technologies aren't as complicated as they sound. Developers will want a means to adapt the application logic and user interface to particular devices given the variation across devices from different vendors or across different models from the same vendor. Moreover, developers will want to be able access and update models of the context, e.g. which kinds of lights are in what positions in a room, so that the app has an idea of which lights to turn on or off etc. to fulfil a particular intent.

These so called semantic models are expressible in terms of graphs of nodes connected together with labelled links. The nodes represent concepts and the links represent relationships between them. Simple libraries allow applications to retrieve models and operate on them, e.g. following links within the graph. W3C recommends that nodes and link labels (aka "predicates") are identified with URLs that can be dereferenced to access graphs that provide further information. This is why the approach is often referred to as Linked Data.

Web developers will soon become proficient at writing code to manipulate Linked Data using simple libraries. You certainly don't need to be an expert in logic or ontology languages. The W3C Web of Things IG could offer a valuable service by working on some tutorial materials that de-mystify this, and show the potential for creating value added services that work with models of devices and the context, whether this is for smart homes, smart cities or smart manufacturing.

[draggett]

I am continuing the discussion on de-mystifying semantic models as issue #93.

[benfrancis]

@benfrancis wrote:

Could you please illustrate with examples what Thing Descriptions could look like using JSON-LD 1.1

Looks like there are good examples of this in the experimental simplified TD:

  "properties": {
    "on": {
      "type": "boolean",
      "links" [{
        "href": "/things/lamp/properties/on",
        "mediaType": "application/json"
      }]
    },
    "status": {
      "readOnly": true, /* inversed default logic for us */
      "type": "object",
      "properties": {
        "battery": {
          type: "number",
          minimum: 0.0,
          maximum: 100.0,
          "links" [{
            "href": "/things/lamp/properties/status/batt",
            "mediaType": "application/json"
          }]
        },
        "rssi": {
          "type": "number",
          minimum: 0.0,
          maximum: 1.0
        },
        "level": "range"
      },
      "links" [{
        "href": "/things/lamp/properties/status",
        "mediaType": "application/json"
      }]
    }
    "brightness": {
      /* FIXME: how to reference "range" to import defintions */
      "links" [{
        "href": "/things/lamp/properties/status",
        "mediaType": "application/json"
      }]
    }
  },
  "actions": {
    "fade": {
      "input": {
        "type": "object",
        "properties": {
          "from": "range",
          "to": "range"
          "duration": { "type": "number" }
        }
      },
      "forms": [{
        "href": "/things/lamp/actions/fade",
        /* encType would be for the request body
           opposed to mediaType, which is for target
           FIXME: can have both meanings based on context (links/forms)? */
        "encType": "application/json",
        /* redundant to default here, just to indicate
           imagine a PATCH Action or a CoAP FETCH Action */
        "http:methodName": "POST"
      }]
    }
  },
  "events": {
    "overheated": {
      "type": "object",
      "properties": {
        "temperature": { "type": "number" }
      }
      "links": [{
        "href": "/things/lamp/events/overheated",
        /* needed, alternative: register URI schemes "http+sse", "http+lp", ... */
        "http:subProtocol": "http:EventSource",
        "mediaType": "application/json"
      }]
    }
  }

[handrews]

    {
        "href": "/things/lamp/actions/fade",
        /* encType would be for the request body
           opposed to mediaType, which is for target
           FIXME: can have both meanings based on context (links/forms)? */
    }

This is precisely why Hyper-Schema has groups of keywords prefixed with either target, submission, or href, for target representations, non-representation request bodies, and URI template data, respectively. It's all much more clear than trying to match RFC 5988/8288 terminology exactly, given that RFC 5988/8288 are solving a more limited problem. After a very large amount of debate we decided it was better to tailor keywords to API usage rather than matching HTML-ish terms.

Earlier versions of Hyper-Schema did exactly the "both meanings based on context" approach and it was both extremely confusing (as far as I can tell, literally no one but the author of draft-04 Hyper-Schema implemented this part correctly) and made numerous simple API concepts impossible because APIs can do a lot more things that HTML forms which are fine with the context-switching.

[sebastiankb]

The new TD version moved to an idiomatic JSON. That means, Properties, Actions, Events are defined as objects.