Define a protocol binding for readmultipleproperties?

[benfrancis]

So far we haven't defined a protocol binding in the Core Profile for readmultipleproperties. An editor's note provides the following explanation:

readmultipleproperties is currently excluded due to the complexities of the request payload format and because it doesn't add much functionality over readproperty and readallproperties.

Basically an HTTP GET request doesn't usually have a body (though the HTTP specification doesn't explicitly forbid it), so people felt including an array of property names in the body would be a bit unusual.

A comment on w3c/wot-thing-description#1349 describes an alternative approach used by the Eclipse Ditto project based on URL query parameters. E.g.:

GET /api/2/things/org.eclipse.ditto:my-thingy-1/attributes?fields=manufacturer,serialNo,productionDate

This is quite a neat solution which could be used as part of the Core Profile. Reading multiple properties could have some values in the case of devices with a very large number of properties.

As an aside, if we added a binding for readmultipleproperties then we could also add a binding for writeallproperties as well for completeness, which would basically have the same design as writemultipleproperties but perhaps with an additional defined error response if not all properties are included in a request.

What do people think?

[benfrancis]

Note: w3c/wot-thing-description#1357 points out that uriVariables are not currently permitted in top level forms, which may make this approach impossible if not addressed.

[thjaeckle]

For writemultipleproperties I would like to point out that JSON merge patch (RFC7396) is an even simpler approach.
As JSON merge patch is already used in some WoT specifications, using it here would be consequent.

[benfrancis]

For writemultipleproperties I would like to point out that JSON merge patch (RFC7396) is an even simpler approach.
As JSON merge patch is already used in some WoT specifications, using it here would be consequent.

Thanks, I have filed a separate issue to discuss that #159

[benfrancis]

Note: w3c/wot-thing-description#1357 points out that uriVariables are not currently permitted in top level forms, which may make this approach impossible if not addressed.

This has now been addressed by w3c/wot-thing-description#1383

[mlagally]

Arch call on April 24th: This is not a blocker but a proposed improvement, removing the "blocks publication" label.

[benfrancis]

I looked into this a bit more, and whilst I like the idea of using uriVariables for this operation, it's difficult to do so without standardising the URL structure (i.e. the name of the uri variable) which is something we've so far managed to avoid.

I think my preferred way of doing this would instead be to standardise a semantic annotation you can add to a URI variable to denote that it's the variable for providing a list of properties to read, e.g.

  "uriVariables": {
    "filter": {
      "@type": "propertyNames",
      "title": "The names of the properties to read",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "forms": [
    {
      "op": ["readallproperties", "writemultipleproperties", "readmultipleproperties"],
      "href": "properties{?filter}"
    }
  ]

However, we've also so far avoided defining a new JSON-LD context for any of the profiles.

I'd really like to add standardised protocol bindings for the readmultipleproperties and writeallproperties operations for completeness, but maybe this should be deferred to the next version.

[mlagally]

We should wait for the TD to land a solution for w3c/wot-thing-description#1685 and revisit in Profile-1.1.

[egekorkan]

We should wait for the TD to land a solution for w3c/wot-thing-description#1685 and revisit in Profile-1.1.

Two comments about this:

1. Profile does not have to use the default verb of TD so no real need to wait for the linked issue above.
2. What does it mean for any profile to not define a binding for an operation? Can this operation be used in a profile but with the freedom that the spec allows or can it not be used at all?

[benfrancis]

@egekorkan wrote:

Profile does not have to use the default verb of TD so no real need to wait for the linked issue above.

Agreed, but my preferred solution would involve defining a TD extension context for the profile and it doesn't seem to be worth it to define that for this one operation (which is itself only an optimisation). I think it's OK to wait until a future version.

What does it mean for any profile to not define a binding for an operation? Can this operation be used in a profile but with the freedom that the spec allows or can it not be used at all?

That's a good question, but essentially all the current profile mechanism does is to enforce a set of assertions on a Thing. Given that there are no assertions saying you can't provide a readmultipleproperties operation, my assumption would be that you can. There are no restrictions on the protocol binding for that operation and the normal defaults apply. That also means that a conformant Consumer can't be assumed to be able to consume that operation.