Clarifications on readmultipleproperties and writemultipleproperties / writeallproperties

[danielpeintner]

(A) readmultipleproperties

The last par in 5.3.1.1 Thing reads as follows:

If not specified otherwise (e.g., through a TD Context Extension), the request data of the readmultipleproperties operation is an Array that contains the intended PropertyAffordances instance names, which is serialized to the content type specified by the Form instance.

Does this mean that in some cases no input array needs to be given and a fixed set of names can be assumed OR do we always need to pass an array on binding level?

(B) Difference between writemultipleproperties and writeallproperties

Is the assumption in the scripting API correct that passing all writable properties to writemultipleproperties OR writeallproperties form lead to exactly the same result? OR are there any differences one needs to be aware of. Hence, the difference is only whether all properties are provided or (maybe) a subset. In a sense writeallproperties seems to be a special case of writemultipleproperties...

Somehow these 3 ops values seem to be under-specified.

relates with w3c/wot-scripting-api#219

[egekorkan]

Somehow these 3 ops values seem to be under-specified.

I agree with this.

Difference between writemultipleproperties and writeallproperties

The idea behind this is that some Things require all of them to be present (why is that I cannot know but I can imagine some implementations that simply look into the key of the input without checking if the key exists). writeall is for me indeed a specific case of writemultiple

Does this mean that in some cases no input array needs to be given and a fixed set of names can be assumed OR do we always need to pass an array on binding level?

I think that a fixed set should be possible even if not allowed by the specification at the moment. In MQTT, one can subscribe to properties/* and get only a subset of properties (because the thing was also publishing to myproperties/temperature)

[benfrancis]

@danielpeintner wrote:

Does this mean that in some cases no input array needs to be given and a fixed set of names can be assumed OR do we always need to pass an array on binding level?

My assumption would be that an array is always provided for readmultipleproperties and never provided for readallproperties.

Is the assumption in the scripting API correct that passing all writable properties to writemultipleproperties OR writeallproperties form lead to exactly the same result? OR are there any differences one needs to be aware of. Hence, the difference is only whether all properties are provided or (maybe) a subset. In a sense writeallproperties seems to be a special case of writemultipleproperties...

I think that is a valid assumption and is the reason we didn't bother specifying a protocol binding for writeallproperties in the Core Profile.

See the Editor's Note at https://w3c.github.io/wot-profile/#h-ednote-5 which explains why we only specified protocol bindings for readallproperties and writemultipleproperties and not readmultipleproperties or writeallproperties:

• An HTTP binding of readmultipleproperties is a bit tricky because HTTP GET requests don't usually have a body, plus it doesn't really add much utility
• writeallproperties is just a special case of writemultipleproperties

This might seem a bit arbitrary but I think readmultipleproperties and writeallproperties mostly exist for completeness and don't necessarily add a lot of value.

[danielpeintner]

My gut feeling tells me that many arguments are coming from reading between the lines or making personal assumptions. Having said that, I think this should not be the case and requires proper specification.

[thjaeckle]

I can give input on how e.g. Eclipse Ditto allows something like readmultipleproperties for an HTTP GET:
We use an optional query parameter (a "field selector") which defines which properties (named "attributes" at our API) to fetch on a resource, e.g.:

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

That would e.g. return such a JSON document:

{
  "manufacturer": "ACME Inc.",
  "serialNo":"12345aaa",
  "productionDate":"2022-01-17T13:11:24Z"
}

If the fields param would be omitted, all properties are fetched, so that would be a readallproperties. The result is a JsonObject of either all properties, e.g.:

{
  "manufacturer": "ACME Inc.",
  "serialNo":"12345aaa",
  "productionDate":"2022-01-17T13:11:24Z",
  "anotherProperty": true
}

Such a "field selector" is a common practice at JSON APIs (keyword: partial request/response) to only fetch a defined subset.
I had the association of a "field selector" when reading about the readmultipleproperties in the spec.

[egekorkan]

I have an idea, inspired by how we describe how security credentials should be sent by the Consumer. Currently, multiple security schemes have the keyword in (https://w3c.github.io/wot-thing-description/#basicsecurityscheme) which tells that the credential should be provided in the header, body, URI etc. Here is a sample TD that introduces the term in in the root level forms and propertyNames. The in can have the values of header, body, uri, static, cookie etc. We can also extend it in the future. For each of the values, we have to say how the form MUST/SHOULD look like.

{
  "properties": {
    "temperature": {
      "title": "temperature",
      "observable": false,
      "readOnly": true,
      "type": "number",
      "forms": []
    },
    "humidity": {
      "title": "humidity",
      "observable": false,
      "readOnly": true,
      "type": "number",
      "forms": []
    },
    "colorTemperature": {
      "title": "colorTemperature",
      "observable": false,
      "readOnly": true,
      "type": "number",
      "forms": []
    }
  },
  "forms": [
    {
      "op": [
        "readmultipleproperties"
      ],
      "href": "/properties",
      "in": "body",
      "htv:methodName": "POST"
    },
    {
      "op": [
        "readmultipleproperties"
      ],
      "href": "/properties",
      "in": "urivariables",
      "htv:methodName": "GET",
      "uriVariables": {}
    },
    {
      "op": [
        "readmultipleproperties"
      ],
      "href": "/properties",
      "in": "cookie",
      "htv:methodName": "GET"
    },
    {
      "op": [
        "readmultipleproperties"
      ],
      "href": "/properties",
      "in": "static",
      "propertyNames": [
        "colorTemperature",
        "humidity"
      ]
    }
  ]
}

[danielpeintner]

I have an idea, inspired by how we describe how security credentials should be sent by the Consumer. Currently, multiple security schemes have the keyword in (https://w3c.github.io/wot-thing-description/#basicsecurityscheme) which tells that the credential should be provided in the header, body, URI etc.

I like that idea.
Having said that, besides in we might need additional information in the end like "how" the information is represented and in which format.

e.g., @thjaeckle mentioned the following example
GET /api/2/things/org.eclipse.ditto:my-thingy-1/attributes?fields=manufacturer,serialNo,productionDate
while I can see different formats also like
GET /api/2/things/org.foo.blas:my-thingy-1/attributes?fields=[manufacturer,serialNo,productionDate]
OR
GET /api/2/things/org.foo.blas:my-thingy-1/attributes?fields[0]=manufacturer&fields[1]=serialNo&fields[2]=productionDate

Note: these are HTTP use-cases. I think we should not forget about other protocols.

[sebastiankb]

from today's TD call:

• it seems that the "in" term approach will be consistent with the security approach that also uses the "in" term
• unclear if this is something we should cover in the TD 1.1 already?
• maybe we can do some experiments in the next PlugFest and decide then if we should postpone it to TD 2.0