Wot-thing-description: Top-level links member and links vs forms

[benfrancis]

Both the JSON-LD and JSON-TD serialisation proposals include links for properties, actions and events.

Links for properties, actions & events

JSON-LD:

"interaction": [
      {
          "@type": ["Property"],
          "name": "status",
          "outputData": {"type": "string"},
          "writable": false,
          "observable": true,
          "form": [{
              "href": "coaps://mylamp.example.com:5683/status",
              "mediaType": "application/json"
          }]
      },
      {
          "@type": ["Action"],
          "name": "toggle",
          "form": [{
              "href": "coaps://mylamp.example.com:5683/toggle",
              "mediaType": "application/json"
          }]
      },
      {
          "@type": ["Event"],
          "name": "overheating",
          "outputData": {"type": "string"},
          "form": [{
              "href": "coaps://mylamp.example.com:5683/oh",
              "mediaType": "application/json"
          }]
      }
  ]

JSON-TD:

"properties": {
  "brightness" : {
    "name": "Brightness",
    "type": "number",
    "description": "The level of light from 0-100",
    "min" : 0,
    "max" : 100,
    "href": "/things/lamp/properties/brightness"
  }
},
"actions": {
  "fade" : {
    "name": "Fade",
    "description": "Fade from one brightness to another",
    "data": {
      "from": {
        "type": "number",
        "min": 0,
        "max": 100
      },
      "to": {
        "type: number",
        "min": 0,
        "max": 100
      },
      "duration": {
        "type": "number",
        "unit": "milliseconds",
      }
    },
    "href": "/things/lamp/actions/fade"
  },
"events": {
  "overheated": {
    "name": "Overheated",
    "description": "The device exceeded its maximum safe operating temperature",
    "data": {
      "temperature": {
        "type": "number",
        "unit": "celcius"
      }
    }
  }
}
}

Possible use cases being:

• Get a value of a property by its URL (e.g. HTTP GET)
• Set the value of a property by its URL (e.g. HTTP PUT)
• Add an action request to an action queue (e.g. HTTP POST)
• Get the status of an action request by its URL (e.g. HTTP GET)
• Cancel an action request by its URL (e.g. HTTP DELETE)
• Get a list of recent occurrences of a particular event (e.g. HTTP GET)

The above examples use HTTP, but the resources could use alternative web protocols like CoAP using coap:// URLs instead of http:// URLs.

Top Level links member

The JSON-TD proposal also includes a top level links member which for convenience can also provide links to a list of all property values, a queue of all actions, a list of all events and a WebSocket endpoint for a Thing.

For example:

  "links": {
    "properties": "/thing/mything/properties",
    "actions": "/things/mything/actions",
    "events": "/things/mything/events",
    "thing": "wss://mywebthingserver.com/things/mything"
  }

The intended use cases being:

• Get the values of all properties of a Thing at once (e.g. HTTP GET)
• Get a list of all actions that have been requested on a Thing (e.g. HTTP GET)
• Get a list of recent instances of all event types being triggered (e.g. HTTP GET)
• Open a WebSocket on a thing to communicate with it (HTTP GET which is upgraded to a WebSocket to use a Web Thing WebSocket sub-protocol (to be defined)).

The general idea is that a Web Thing Description provides metadata about a thing as well as links to its resources on the web, resolvable by URLs (which could be http:// URLs, coap:// URLs or any other web protocol using a different scheme). These resources may include properties, action requests, events or an alternative top level resource for the thing itself (e.g. a WebSocket URL for a Thing).

Is this top level links member useful and should it be added to the main Thing Description specification?

[draggett]

The JSON-TD example could be simplified further by stripping out the "data" object so that "from", "to" etc. are peers of "name" and "description". In my implementation, I chose to use "request" and "response" rather than "from" and "to" as I believe that request and response are unambiguous and as such easier to understand.

I also allowed properties to be simplified when you just need to give the type and don't need to specific additional metadata. You then just provide the string literal for the type name rather than an object that declares the metadata for that property. For use cases where several properties have the same type, I allow for application defined named types, that can declare the required metadata.

[benfrancis]

The JSON-TD example could be simplified further by stripping out the "data" object so that "from", "to" etc. are peers of "name" and "description". In my implementation, I chose to use "request" and "response" rather than "from" and "to" as I believe that request and response are unambiguous and as such easier to understand.

I don't understand what you mean by request and response here. from, to and duration are intended as arguments to submit with the fade action request. For example to tell a light to "Fade from 100% to 50% over 200 milliseconds".

That might be better discussed in #66.

[draggett]

I am not convinced of the need for specifying access URLs separately for properties, actions and events. This seems redundant compared with a default rule that derives the URL from a single access URL at the level of the thing. Moreover, why use HTTP for access rather than WebSockets which is great for asynchronous messaging over a single connection? In my work, I just use HTTP to access the thing description along with a security token. This includes the server-side work needed for authentication and access control. I then use a shared WebSocket connection for property updates, events, action requests and responses. The events include life cycle events and metadata updates, including the addition of new properties etc.

If you don't use WebSockets, you need another means to listen for events and delayed action responses. I've explored using Server Sent events over HTTP which works nicely, but it isn't as efficient as WebSockets, and more over isn't as widely supported by web browsers.

[draggett]

I've followed @benfrancis suggestion to continue the discussion on action requests and responses in #66

[sebastiankb]

@benfrancis

Possible use cases being:

• Get a value of a property by its URL (e.g. HTTP GET)
• Set the value of a property by its URL (e.g. HTTP PUT)
• Add an action request to an action queue (e.g. HTTP POST)
• Get the status of an action request by its URL (e.g. HTTP GET)
• Cancel an action request by its URL (e.g. HTTP DELETE)
• Get a list of recent occurrences of a particular event (e.g. HTTP GET)

I'm wondering how does the client knows that it can execute, e.g., a PUT on a property? For that purpose we using the _writable_ key in the Property definition of JSONLD-TD. Is this set true than also a PUT is associated, otherwise only a GET.

[draggett]

@benfrancis writes

I'm wondering how does the client knows that it can execute, e.g., a PUT on a property? For that purpose we using the the writable key in the Property definition of JSONLD-TD. Is this set true than also a PUT is associated, otherwise only a GET.

This sounds like it is mixing up different levels of abstraction. The thing description declares whether a property is writeable or read-only. The protocol to be used is at a lower layer and comes under the rubric of protocol binding. In my view the thing description should minimise the need for protocol binding metadata. Given that we can get away with just a few protocols that is definitely doable.

[mkovatsc]

Both the JSON-LD and JSON-TD serialisation proposals include links for properties, actions and events.

This is related to the links vs forms question. Thinking of the TD as "HTML for Things", this can be seen as follows: They are not links to related Things (pages) or to include externalized metadata (e.g., stylesheet). They are about the operational/live data, and hence similar to forms that tell the client how to formulate a request to interact with the Thing ("active" page / REST resource). For Actions, this is the most clear, as they might need a request payload to be described (e.g., media type). For Properties it is like a form with method="GET" that allows to parameterize what to get/read.

When we assume sensible defaults, most of the request might be clear and needn't be stated -- target resource is enough. If the Thing was not implemented according to the defaults (many many IoT devices are not and will not be), we need additional descriptions, which, as Dave states correctly, come from the Binding Templates. This includes aspects like a different method or expected header fields (see X-headers in many Web application, OCF's and oneM2M's usage of CoAP, etc.). Some defaults are easy (e.g., GET to read, PUT to write, POST to invoke Action), some are tougher (e.g., media type application/json common for Raspberry Pi class of Things, while many IoT devices use CoAP together with application/cbor and would benefit way more from a smaller TD...)

Overall, when Mozilla or anyone else implements Things from scratch following the defaults, they can simply opt-out of the protocol binding stuff and still be fully W3C WoT compliant.

Top Level links member

We also want this -- @sebastiankb I asked you recently if you can push this into the Prague release...

Yet I don't see a use case to point to these Interaction collection resources or any other resource at a different abstraction level. The "links" member should primarily be about expressing the relation to other Things and maybe services at a similar level, e.g., marketplaces or directories. Expressing the relation includes having a rel attribute and potentially other features of RFC5988.

[benfrancis]

@draggett wrote:

I am not convinced of the need for specifying access URLs separately for properties, actions and events. This seems redundant compared with a default rule that derives the URL from a single access URL at the level of the thing.

Some feedback we received early on was that the specification should not mandate the URL structure of a web thing. This is why we took the approach of the Thing Description acting as a root resource, which links to other resources of the Thing using a HATEOAS approach. This gives Thing developers more freedom in designing their own URL structure for Things in the same way they can design their own URL structure for websites, for example using languages other than English in their URLs, retro-fitting a Thing Description for an existing HTTP-based API or providing a Thing Description for API endpoints using another URL scheme or origin.

Moreover, why use HTTP for access rather than WebSockets which is great for asynchronous messaging over a single connection? In my work, I just use HTTP to access the thing description along with a security token. This includes the server-side work needed for authentication and access control. I then use a shared WebSocket connection for property updates, events, action requests and responses. The events include life cycle events and metadata updates, including the addition of new properties etc.

The majority of commercial IoT services like those from Amazon, Google, Nest, Microsoft, Apple and EVRYTHNG provide a REST API to interact with Things, but they all do so in a slightly different incompatible way. Our goal with our proposed HTTP binding is to provide a standard way to do this so that these services might inter-operate.

Re-purposing HTTP for IoT also brings with it a huge range of tried and tested tools and technologies. Apart from the fact that there's an HTTP implementation in almost all programming languages, you can also re-use technologies like OAuth, which we're currently using in Mozilla's gateway implementation, to do things like authorize different levels of access to certain things or properties of things to different consumers of the API using a JSON Web Token. It also makes it easy to integrate with existing web services and IoT services like IFTTT. By using HTTP, you can interact with Things on the Web of Things like any other web service.

HTTP is obviously not ideal for some IoT use cases, which is where WebSockets and IoT-focused protocols like CoAP come in. That's why we've proposed both HTTP and WebSocket bindings.

If you don't use WebSockets, you need another means to listen for events and delayed action responses. I've explored using Server Sent events over HTTP which works nicely, but it isn't as efficient as WebSockets, and more over isn't as widely supported by web browsers.

In Mozilla's proposed bindings you can choose to long-poll a list of events using HTTP (or use some other existing technology like web hooks or server sent events), or subscribe to a type of event over WebSockets.

[benfrancis]

@sebastiankb wrote:

I'm wondering how does the client knows that it can execute, e.g., a PUT on a property? For that purpose we using the writable key in the Property definition of JSONLD-TD. Is this set true than also a PUT is associated, otherwise only a GET.

Our original intention was to defer this to the protocol level, e.g. by doing an OPTIONS request on a URL. However, we have discussed the idea of a "writeable/writable" attribute for properties, the benefit being that you don't have to make multiple HTTP requests to find out whether a property is writeable or not.

We could consider adding this to the JSON-TD proposal, I filed https://github.com/w3c/wot/issues/383

[benfrancis]

@draggett wrote:

@benfrancis writes
I'm wondering how does the client knows that it can execute...

I didn't write this BTW.

This sounds like it is mixing up different levels of abstraction. The thing description declares whether a property is writeable or read-only. The protocol to be used is at a lower layer and comes under the rubric of protocol binding. In my view the thing description should minimise the need for protocol binding metadata.

I disagree with this. It's my view that the Thing Description should be a concrete description of a web thing which links to its web resources, in the same way that a Web App Manifest describes a web app and links to its icons, start URL, Service Worker etc. Not an abstract piece of metadata which needs a separate binding document in order to be useful.

Given that we can get away with just a few protocols that is definitely doable.

Surely this is an argument for not needing to separate out the protocol binding? Web protocols all use URLs, so all that is needed are hyperlinks/link relations from the Thing Description to its web resources using URLs. That could include http://, https://, coap://, coaps://, ws:// and wss:// URLs.

I see this as a fundamental unresolved issue in the definition of the Web of Things vs. the Internet of Things which we have still failed to agree upon. Many members still seem to want the Web of Things specifications to be applied to non-web and even non-Internet protocols. By sticking to web protocols we can drastically simplify the specification(s) and leave the definition of underlying edge protocols to other standards bodies.

[benfrancis]

@mkovatsc wrote:

Thinking of the TD as "HTML for Things", this can be seen as follows: They are not links to related Things (pages) or to include externalized metadata (e.g., stylesheet). They are about the operational/live data, and hence similar to forms that tell the client how to formulate a request to interact with the Thing ("active" page / REST resource). For Actions, this is the most clear, as they might need a request payload to be described (e.g., media type). For Properties it is like a form with method="GET" that allows to parameterize what to get/read.

This is an interesting analogy, but I'm not sure "HTML for Things" is the best way to describe the Thing Description. Not least because the Thing Description is a machine-readable representation of a resource which may also have a human-readable HTML representation (in Mozilla's gateway implementation we use HTTP content negotiation for the server to decide whether to send a JSON representation or an HTML representation for the same URL).

I see the Thing Description format more like an Interface Description Language (IDL) which describes an HTTP/CoAP/WebSocket API for a Thing using a HATEOAS approach. The Thing Description is a top level resource which links to other resources using link relations (see here for an equivalent example serialised in XML).

In this way a Thing is more like a website or web app which consists of multiple resources (pages), rather than a represented as a single resource (page).

When we assume sensible defaults, most of the request might be clear and needn't be stated -- target resource is enough. If the Thing was not implemented according to the defaults (many many IoT devices are not and will not be), we need additional descriptions, which, as Dave states correctly, come from the Binding Templates.

The forms approach is an interesting way of leaving the mechanics of the API for a Thing completely open ended and leaving it up to the Thing Description to define an implementation-specific protocol binding for each Thing. Would this not be unnecessary if for example an HTTP binding specification defined how thing, property, action and event resources could be interacted with using specific HTTP verbs? e.g. use a PUT on a property URL to set a property?

This includes aspects like a different method or expected header fields (see X-headers in many Web application, OCF's and oneM2M's usage of CoAP, etc.). Some defaults are easy (e.g., GET to read, PUT to write, POST to invoke Action), some are tougher (e.g., media type application/json common for Raspberry Pi class of Things, while many IoT devices use CoAP together with application/cbor and would benefit way more from a smaller TD...)

Apart from custom headers (which hopefully aren't necessary), all of this could be described with a link relation.

Overall, when Mozilla or anyone else implements Things from scratch following the defaults, they can simply opt-out of the protocol binding stuff and still be fully W3C WoT compliant.

Exactly. For a JSON Thing Description served over HTTP an http:// scheme and application/json MIME type could be assumed as the default, unless specified otherwise (e.g. a coap:// URL and application/cbor MIME type as in your example, although in this case you might also want to serve the Thing Description itself as CBOR over CoAP...)

Top Level links member
We also want this -- @sebastiankb I asked you recently if you can push this into the Prague release...
Yet I don't see a use case to point to these Interaction collection resources or any other resource at a different abstraction level. The "links" member should primarily be about expressing the relation to other Things and maybe services at a similar level, e.g., marketplaces or directories. Expressing the relation includes having a rel attribute and potentially other features of RFC5988.

Hopefully I described the intended use cases above, I don't see them as a separate level of abstraction, it's just a case of linking from one web resource to another.

[benfrancis]

One thing I don't love about the current JSON-TD proposal is that there is the separation between the top level "links" member and the links provided for individual properties, actions and events. There might be a neater or more consistent way to structure this but we couldn't think of one which didn't add a lot of complexity.

[mkovatsc]

I'm not sure "HTML for Things" is the best way to describe the Thing Description

"because the Thing Description is a machine-readable representation of a resource which may also have a human-readable HTML representation" is actual a matching way to see it. Humans would receive an HTML representation that contains the general metadata of the Thing such as name, location, etc. and a number of forms (e.g., buttons) to interact with the Thing. A machine client would want a similar representation that it can understand. It would do so through content negotiation on the same resource. Furthermore, machine clients need machine-understandable semantics (Linked Data!) instead of human-readable text or icons. The LD-based TD does exactly this.

Your HATEOAS argument does not really work, as the payloads exchanged for interactions (reading a Property, invoking an Action) do not include hypermedia controls, only data. The hypermedia controls are in the TD and clients would browse from Web pages or TDs to other TDs and would submit forms they found in TDs.

The top-level triples (name, location, etc. -- yes we are missing some common definitions here) correspond to the text and images displayed to humans. The top-level links point to related resources/Things and correspond to metadata links (<link />) and HTML references (<a>...</a>). The TD forms correspond to the HTML forms a user would use for interaction (e.g., with input fields, dropdown boxes, buttons) -- even if they might be implemented using CSS and AJAX instead of classic HTML forms. Properties can be argued both ways, but I would say they are more like <img /> src URIs than browsable links, as we retrieve data without any further hypermedia controls; there are also GET forms and writing a property would require a form anyway.

Maybe this is related to your dissatisfaction of the mismatch between JSON-TD top-level links and Interaction links...

[benfrancis]

We don't need to re-invent HTML in JSON.

We're just defining a web resource which contains some metadata and links to other web resources. Perhaps HATEOAS was a bad example because that's quite a loaded term, it's really more more like a web app manifest but for a "thing" rather than an app.

If we define a concrete HTTP binding which defines the HTTP methods that can be used with a defined set of resource types (e.g. a PUT to set a property, a POST to request an action, a DELETE to cancel an action) then we don't need these complex "form" definitions at all. Just links.

[mkovatsc]

We don't need to re-invent HTML in JSON

Re-inventing HTML would be bad. What we need are the good parts of HTML, omit the human-centric parts, and combine it with what machine clients need. Such a machine client can an autonomous Thing or a UI that renders TDs automatically for a specific context, which includes multi-modal interfaces for accessibility.

This typed resource you are proposing is actually the exact opposite of HATEOAS.

Web app manifests contain metadata to display installed apps and launch information. For me, this is way more of a stretch.

concrete HTTP binding

We said to address this with defaults. So for Things implemented using the defaults, there is basically no information in the form; a rename is possible if that solves your issue. It is meant to serve as an extension point to be able to describe existing platforms and standards such as OCF -- something we definitely need to allow for convergence toward WoT defaults. Let me update the simplified proposal with what we discussed so far. It will be the target after Prague and will be discussed at the Prague F2F.

[benfrancis]

Forms in HTML still seem like a strange analogy to me.

An HTML link element has:

• href
• type
• rel

Internet Explorer 4 also had a methods attribute which listed the methods which could be performed on a link, but this was largely redundant because an HTTP OPTIONS request achieves the same result and is part of the HTTP protocol.

An HTML form element has:

• action (URL)
• enctype (application/x-www-form-urlencoded or multipart/form-data)
• method (POST or GET)

Example 15 in the Binding Templates specification has href and a mediaType and looks a lot more like a link relation than a form to me.

Example 16 has href, mediatype, rel and http:methodName. The first three again look a lot like a link relation.

I'm guessing that it's http:methodName which has led you to draw a parallel with HTML forms.

When providing a URL for a property, why do you need two separate "forms" for GET to read it and a PUT to write to it? Why not just provide a link to the property URL and let the protocol take care of the rest?

It seems what you're trying to do is to allow the Thing Description to describe an HTTP API, a CoAP API or an MQTT API to avoid the need for concrete protocol bindings like the HTTP binding proposals by Mozilla and COMPOSE. Apart from the fact that the HTTP protocol already provides a mechanism to get this "available methods" information (an OPTIONS request), I'd argue this still doesn't provide enough information for a client to actually consume the API without a further specification which defines the format of the responses. Knowing that the data is serialised in JSON is not enough.

It is meant to serve as an extension point to be able to describe existing platforms and standards such as OCF -- something we definitely need to allow for convergence toward WoT defaults.

This seems to be the crux of the requirement you're trying to accommodate. The ability for the W3C Thing Description to describe a multitude of existing IoT protocols, rather than converge on a single data model and API for the web.

I would actually question whether this is a good idea. In practice I can't imagine a client which will be able to automatically infer from the Thing Description alone how to consume APIs from various existing protocols like OCF. It would require the client to implement a multitude of data formats and protocols in order to interact with those devices, which seems like the opposite of what we're trying to achieve in making the web a unifying application layer for IoT.

Another way of dealing with OCF, which doesn't conform to the W3C WoT data model, would be to bridge OCF to the W3C's definition of the Web of Things using a gateway. I notice that OCF already has a OCF Bridging Specification which emerged for exactly this kind of use case, in bridging AllJoyn to OCF.

By taking this approach, and defining a concrete HTTP-based API for interacting with web things, a Web of Things client could talk to any web thing with a simple implementation of a defined JSON data format and HTTP+WebSockets API. This would allow for real ad-hoc interoperability.

[mkovatsc]

You seem to only focus only on the naming, not the concept. A form is always needed when more than a simple consumption is happening. A form is used to construct more complex request that may include payload. When all Interactions are reduced to a link to typed resources, we lose the point of metadata and the key aspects of the Web that it made scale and evolve.

I agree, reading a Property can be put in the 'link bucket' and only having writing a Property, Actions, and Events in the 'form bucket'. Yet it appears cleaner to me, to put all Interactions into the 'form bucket' instead.

When we discussed the TD vocabulary, we ended up with terms that were clear to most of us, instead of terms that were picked from other specifications. So far, most people appreciated this strategy; for positioning it within other specs, the other might have been better.

TD form concept

• href --> action -- the target resource
• mediaType --> enctype -- how to encode the payload
  
  
  
  • Here we still have an issue with, as we assume requests and responses would use the same, which might be bad. HTML forms have the limitations that the media type of the action result cannot be specified.
  
  
• *:method --> method -- HTML has a historical limitation to GET and POST here that must be fixed
• rel --> new/maybe related to name -- HTML is human-centric and lacks the ability to express form relations; this is definitely a MUST for WoT/machines.

Prescriptive bindings are still off-limits to me because:

• There is no point in creating yet another IoT silo.
• We have enough experience in gateways and system integration and that we appreciate a uniform, metadata-driven approach to manage the complexity.

@mmccool Can you add on the last point for OCF? (needing to bridge UPnP, AllJOyn, and OIC)
@mjkoster Can you add on the last point for SmartThings? (needing to bridge even more)

[zolkis]

I also think the main use case for WoT is bridging IoT to the Web. For each protocol suite like OCF we'd just need to provide a library implementing WoT interactions. That would be much simpler to implement if there was a well defined Web API, either RESTful or scripting. TDs and reasoning based on TDs may automate that process, but we could have a slow start on that.

[benfrancis]

There is no point in creating yet another IoT silo.

The World Wide Web of pages is pretty much built on a single protocol (HTTP) and markup language (HTML). Is that a silo? Trying to "describe" multiple existing silos just allows those silos to continue to exist and requires a client to implement support for all of them.

[handrews]

I'm just going to point out that JSON Hyper-Schema now has a much more thorough and flexible model for links and forms than back in the draft-04 days, if anyone would be at all interested in reconsidering it.

I know it was previously considered and rejected, but draft-07 is very different from draft-04, and I'm happy to answer any questions or take an existing example from somewhere and show what it would look like in Hyper-Schema.

https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-01

[mkovatsc]

The World Wide Web of pages is pretty much built on a single protocol

You seem to ignore that it took more than 20 years that the Web is what it is today. It started as a hypertext system for documents only. A lot of different technologies were involved over the time, there was a browser war.

You say all this can be skipped through a company that has no experience with devices?

If you simply want to put a pure Web gateway in front of custom gateway implementations, why do the existing Web technologies not do the job? Why not provide OpenAPI specifications for your gateway and be done?

[mkovatsc]

In the TD call today, we officially agreed to include a top-level link member in the JSON-LD TD: https://github.com/w3c/wot-thing-description/issues/94

This will be included for the Prague Working Draft.

[zolkis]

Right, what we want is to be able to fetch WoT TD's for IoT devices (manufacturer page, service, etc), and WoT gateways would bridge the rest by providing TDs for them. At the moment the latter group is much larger, so we tend to it first :).

Besides, because deployment is out of scope, IoT installations need to explicitly support and provision for WoT, including security/access rights etc. They will likely do that by a WoT gateway, as it is the simplest way.

Why not provide OpenAPI specifications for your gateway and be done?

Well, I couldn't help thinking actually we are working on a web'ified CORBA ;).

[draggett]

We can dramatically simplify the need for communications metadata if we have a default protocol binding plus the means to name other protocol bindings, rather than trying to define complex declarative descriptions for binding to arbitrary protocols. Occam's razor applies, we should adopt the simplest solution that provides a flexible scalable solution to commercial needs for open markets of IoT services.

Like Ben I believe that the market doesn't need many protocols for communication between web of things application servers. A default protocol binding based upon HTTP and WebSockets will suffice for the vast majority of use cases. Where interoperability is needed with other protocols, these could be handled in one of two ways. The first is to use a gateway where an application is used to republish a thing. The second is to rely on a protocol driver that is either preinstalled or installed upon need by the application platform based upon the communications metadata.

[mjkoster]

This is a pretty broad discussion wrt the subject line. I'm less concerned about the syntax and vocabulary than I am about being clear about some of the design patterns and concepts we have developed in the WoT work to date.

It seems like we agree on the need for abstract interaction classes that can expose events, actions, and properties. Whether we have a metaclass label in the format for "interaction" is in many ways a serialization/data model question and does not have much impact on the information model.

It also seems like we agree that a data schema description is needed, to accommodate design freedom in APIs. Here is where I think IoT/WoT may be different in requirements from the internet of documents. Representations from connected things are fundamentally different from representations of text in a document. More descriptive power about shape, type, and structure seems to be needed. Also, the ratio of data to metadata seems to be inverse between documents and things. This from observations of popular design patterns.

The idea of link vs. form should be more or less familiar to any hypermedia system. We decided to use the link construct to describe the relationship between document elements, and the form construct to describe the protocol hooks for an interaction.

• Whether we need a form or not seems to be the meat of this discussion and that of a similar topic in the binding templates issues. Of course, the form could be made optional if the mediatype itself provides enough information as to the expected data shapes and protocol options. I think this is what we have come to expect from HTML and document representations.

The form is particularly useful in adapting to existing device protocols where a generic driver (CoAP, HTTP) can be used to adapt to various implementations (OCF, LWM2M) simply by setting the methods and a couple of header options. It's really not that big a deal.

The form is also important for adapting to existing REST and REST-like APIS that are exposed by services. We currently find ourselves in a cycle of multiple engineering collaborations for the simple purpose of impedance matching one API and data model to another, where the underlying transfer protocols are the same. The idea of protocol bindings enables APIs and data models to evolve in a more loosely coupled way.

As an example, consider that a user of OMA LWM2M will have an HTTP/TLS web proxy to their devices that exposes the LWM2M/IPSO data model in a cloud API. This will apply to many OneM2M compliant systems due to the LWM2M interworking proxy.

A declarative approach will be much easier to maintain than custom software drivers. The alternative, having a set of opaque application level gateways with a prescribed "northbound" protocol and internal translations, is not good for a number of use cases. We think that given the advent of IP networking and common transfer protocols, that the hypermedia system can and should be extended to create an adaptation layer.

We are at the same time exploring middleboxes in the system (proxies) where translation can be done to support clients that may not have the adaptation layers, but at this point would not want to prescribe that as the only solution.

Of course, there may be a gateway business to be exploited but that is considered by many not to be the ideal solution.

[benfrancis]

@mjkoster: Thank you for explaining this, you make some strong arguments.

Here is my concern. What does a Web of Things client look like? If the Thing Description merely describes hundreds of existing IoT protocols, how does a client communicate with all of those devices? Will the client not have to implement each individual protocol and data format? How does this help with fragmentation? Even if you can somehow come up with a declarative format for describing any Internet or non-Internet protocol which gives the client all the information it needs (which I doubt), the client still needs to know how to parse potentially hundreds of different data formats communicated over those protocols.

Before the World Wide Web emerged there were multiple competing hypertext systems and proprietary graphical user interfaces from the likes of AOL and Compuserve. Today's web was made possible by converging on a very small number of royalty free protocols and data formats (in particular HTTP and HTML), not by creating a declarative description format which could describe all of those different proprietary hypertext systems and magically connect them together.

For the cloud integration pattern, HTTP/WebSockets & JSON are arguably already the de-facto standard for IoT when you look at IoT cloud services from the likes of Amazon, Google, Nest, Microsoft, EVRYTHNG etc. For the direct integration pattern (where the device itself exposes a Web of Things API) HTTP & JSON are arguably too heavyweight. We should therefore leave the door open for future web protocols to evolve like CoAP (or "HTTP/3"?) which still provide URLs on the web, and more efficient data formats like CBOR.

But ultimately I believe interoperability in IoT is better served by creating a unified application layer using the web as an abstraction and converging on a very small number of protocols and data formats, rather than trying to create magic declarative glue that tries to bind all these non-web and non-Internet systems together, whilst still requiring that applications directly implement numerous underlying IoT protocols.

Representations from connected things are fundamentally different from representations of text in a document. More descriptive power about shape, type, and structure seems to be needed. Also, the ratio of data to metadata seems to be inverse between documents and things. This from observations of popular design patterns.

Perhaps a better comparison is between existing REST web services and Things exposed as web services. Are "things" really so different than other web services? Exposing things as web services seems to be working pretty well across the industry, each implementation just does so in slightly different incompatible ways.

The form is particularly useful in adapting to existing device protocols where a generic driver (CoAP, HTTP) can be used to adapt to various implementations (OCF, LWM2M) simply by setting the methods and a couple of header options. It's really not that big a deal.

It is a big deal if it serves to maintain or increase fragmentation in IoT rather than forward the stated goal of reducing fragmentation.

The form is also important for adapting to existing REST and REST-like APIS that are exposed by services. We currently find ourselves in a cycle of multiple engineering collaborations for the simple purpose of impedance matching one API and data model to another, where the underlying transfer protocols are the same. The idea of protocol bindings enables APIs and data models to evolve in a more loosely coupled way.

I do understand the argument for backwards compatibility with existing REST services. Ideally following the principles of REST all you would need to achieve this is links with "rel" and "media type". But practically speaking the problem is not the protocol but the data formats used in the payloads of the HTTP requests, which the Thing Description alone can not describe.

A declarative approach will be much easier to maintain than custom software drivers. The alternative, having a set of opaque application level gateways with a prescribed "northbound" protocol and internal translations, is not good for a number of use cases.

Can you provide these use cases? From what I've seen so far the gateway approach seems like the best solution to bridging what you might call "legacy" or non-web protocols and data formats to the Web of Things.

[draggett]

I should add that an alternative to a declarative model for the details of each protocol is to instead use a URL that uniquely identifies a given protocol binding and which can be used to determine if an application platform already supports a given protocol binding, or it can be used to identify and install a software driver for that protocol binding, or it can be used to identify a gateway that can act as a broker between different protocols.

This use of unique identifiers for protocol bindings seems much more scalable than requiring fully declarative solutions. It further allows for smart gateways that can be extended through software and hardware upgrades. In addition, it is much easier for us to standardise. We just need to define a predicate and to register URLs for an initial set of protocol bindings along with a process for others to follow when they want to register additional bindings.

[benfrancis]

@draggett wrote:

I should add that an alternative to a declarative model for the details of each protocol is to instead use a URL that uniquely identifies a given protocol binding

Can you provide examples? What would this look like for HTTP for example? Although practically more feasible, I'd argue this still doesn't do anything to address fragmentation.

and which can be used to determine if an application platform already supports a given protocol binding, or it can be used to identify and install a software driver for that protocol binding

This doesn't sound much like the web to me, it sounds more like native packaged app platforms which require you to download a new app to manage each device. Would you agree? This is in fact one of the main problems with IoT I'm hoping the Web of Things will fix.

I think this again comes back to the question of whether we're building a Web of Things where things can be monitored and controlled over the web, or a Web about Things where we just serve metadata describing things in the real world which use a multitude of non-web IoT protocols that clients must individually support.

If it's the former, which I hope it is, then really links should be sufficient to tell a Web of Things client how to interact with a web thing, given a concretely defined web protocol binding and data format.

[draggett]

Can you provide examples? What would this look like for HTTP for example? Although practically more feasible, I'd argue this still doesn't do anything to address fragmentation.

I completely agree with the importance of convergence on very small set of widely supported Web protocols, but see this as an extensibility point and a matter of future proofing. We would define the predicate and the identifier for the standard protocol binding for HTTP and WebSockets and assume this as the default for JSON based thing descriptions, as known from the media type, e.g. application/json+td.

This metadata is also key to interpreting communication metadata that enable app platforms to access a thing. For the default HTTP/WebSockets, I propose we define metadata items that specifies the URLs for the HTTP and WebSockets end points, together with the convention for using the path constructed from the thing description for each property or sub-property etc. since this avoids developers being required to provide the URLs separately for each property and sub-property. I can provide more details if this isn't sufficiently clear.

[mkovatsc]

I completely agree with the importance of convergence on very small set of widely supported Web protocols, but see this as an extensibility point and a matter of future proofing.

Great, I fully agree!

convention for using the path constructed from the thing description for each property or sub-property etc.

Here, I unfortunately do not agree. Each server must be able to fully govern its namespace, i.e., how it forms URI paths. Furthermore, this path construction would disallow to augment existing Web Things and/or services with a TD, although besides the path they would otherwise be fully capable. Just like on the Web, URIs should be separate from resource relations and meaning.

e.g. application/json+td

Media Types only have to parts, the "top-level type" basically always being application and the "subtype name" such as json or atom+xml being an opaque string without hierarchy. The + notation is purely a convention, however, the convention is "application format name" + "generic serialization fomat", so that it is usually something+json, something+xml, something+cbor, etc.

Hence, in our case application/td+json, on which we still reached consensus, I would say.

[draggett]

Each server must be able to fully govern its namespace, i.e., how it forms URI paths.

That has little to do with the idea of a default that exploits property names etc. Servers can of course choose what base URI they use. For a WebSockets sub-protocol. messages for updating a property would use the property name.

[mjkoster]

The whole point of declarative protocol bindings is to reduce the number of protocols and formats that need to be supported.

As mentioned in this comment, the declarative protocol binding is a hypermedia control to the transfer layer, which enables layered approach to the second-order protocol choices (POST vs. PUT, header options, how notification subprotocols work...) and enable the driver to use a simple HTTP protocol engine with header configuration, rather than needing any special drivers.

It's really not super complex and we are only talking about HTTP and CoAP, and MQTT. Oh and some Websocket binding, which doesn't even have a transfer layer, so arguably websockets needs declarative bindings even more. We should probably consider using CoAP as a transfer protocol on Websockets and be done with the issue...

The alternative is creating a mediatype which defines transfer layer mapping constraints. Would there be a CoAP one and an HTTP one? Having only one of these that everyone uses seems like a stretch at this point and will only work as a common northbound interface specification for a gateway, with limited cross-domain applicability (i.e. mostly smart home oriented).

The declarative protocol binding allows us to use stock HTTP, CoAP, application/json, application/cbor while not needing to define a new set of fixed constraints.

So it seems we are back to the core discussion point.

[draggett]

The whole point of declarative protocol bindings is to reduce the number of protocols and formats that need to be supported.

Well declarative bindings wouldn't be needed if we just had one or two ...

[sebastiankb]

There is a similar discussion here: https://github.com/w3c/wot-thing-description/issues/151

Can we close this issue here and continue the discussion there?

[benfrancis]

There is a similar discussion here: #151
Can we close this issue here and continue the discussion there?

I think the issue of "links vs. forms" is separate and still un-resolved from Mozilla's point of view.

"forms" may make some sense for actions, but it makes no sense for properties and events. "links" can be used for properties, actions and events.

I suggest keeping this issue open to discuss further, or close it and re-open #85.

[jaller94]

My point on the "links vs. forms" topic for properties and events is:

They should be called links in analogy to the HTML <link> tag which also includes a rel descriptor, a path and an optional media type (even if not in the same format). HTML header links are intended to be read by machines instead of humans just as much as they are in the Web Thing specification. They link to CSS documents and RSS feeds which are up to the browser’s implementation of how to load and display.

As benfrancis, I struggle to see the analogy to forms for properties and events. Forms tend to have multiple properties which get submitted to one endpoint. This would make sense for actions which can require multiple values to be set. The input description of an action object seems form-like to me.

For the sake of consistency I recommend the use of link.

[draggett]

My understanding is that links are intended for declaring the relationship between things, e.g. a part of relationship, whilst forms are for the communications metadata for the Web of Things platform to exchange messages over whichever protocols are supported by the platform exposing a thing. Such communications metadata may be associated with individual properties, actions and events. I assume that form was proposed by analogy with how the HTML form element is used to specify an interaction between a web page and a server to submit some data and show the results as a new page.

[handrews]

@benfrancis @JAlanBird @draggett My view of "links" matches @draggett's. As for "forms", my view is similar, but for JSON Hyper-Schema I've been working on an idea of "operations", which have an intent (instead of a rel), and keeping that concept a bit separate from "forms", which I think of as the input interface for an operation. Although in part I'm using "operation" to appeal to people coming from an OpenAPI-ish approach, and because I have noticed that many, possibly most people are unlikely to separate "forms" from "HTML forms".

[mkovatsc]

We have reached some consensus that we are looking for the definition of hypermedia controls that allow "operations" on resources, or more general context. There are two competing concepts, "links and forms at the same level" vs "links with operations on top", which are further discussed here:

https://github.com/w3c/wot-thing-description/issues/179