Question: What should be the response to a readAllProperties message?

[benfrancis]

In my strawman proposal the response to a readAllProperties message is a propertyReadings message which contains a map of key-value pairs showing the values of all properties in one message. E.g.

{
  "thingId": "https://mythingserver.com/things/mylamp1",
  "messageType": "propertyReadings",
  "data": {
    "on": true,
    "level": 50
  },
  "timestamp": "2021-11-16T16:53:50.817Z"
}

@RobWin suggested that the response should instead be individual propertyReading messages which each contain the value of a single property. This would re-use the propertyReading format already used in response to readProperty and observeProperty operations, e.g.

{
  "thingId": "https://mythingserver.com/things/mylamp1",
  "messageType": "propertyReading",
  "property": "on",
  "data": true,
  "timestamp": "2021-11-16T16:53:50.817Z"
}

The thinking being that if there are lots of properties, and some take a long time for a device to read, that the Consumer can start receiving the values of each property as soon as it is read without having for all the properties to be read. He suggests this would be more in-keeping with the streaming approach of a real-time protocol.

I explained that the reason I designed the response in the way that I did was to conform to section 5.3.3.1 of the Thing Description specification which says:

"The data schema for each of the property meta-interactions is constructed by combining the data schemas of each PropertyAffordance instance in a single ObjectSchema instance, where the properties Map of the ObjectSchema instance contains each data schema of the PropertyAffordances identified by the name of the corresponding PropertyAffordances instance."

This is also consistent with the way it's done in the HTTP Basic Profile.

I'm concerned that if the property readings are sent individually it might increase implementation complexity for Consumers, since they will have to figure out when they have received all the property readings (which may not be straightforward if there are writeOnly properties or permissions issues). It also means that if we introduce some form of correlation ID (as some people have suggested) to associate responses with requests, there would be multiple responses for a single request.

I wondered whether other people have an opinion on whether readAllProperties should return a single propertyReadings message, or multiple propertyReading messages? And would the latter be conformant with the Thing Description specification?

[RobWin]

I'll copy my comment here as well:

I understand your rationale for aligning with section 5.3.3.1 of the Thing Description specification and ensuring conformance with the HTTP Basic Profile. However, I think we need to consider the practical implications and typical usage patterns of observeallproperties and readallproperties, even if they are listed as property meta-interactions.

The observeallproperties operation is generally expected to subscribe to all properties but may only send updates for individual properties when they change, rather than bundling all properties into a single message. So for this operation the description also doesn't apply, correct?

Regarding readAllProperties or readMultipleProperties, I agree that a Consumer could collect and aggregate multiple responses for consistency, but it doesn’t necessarily have to wait for all messages before acting. A more reactive approach would allow partial updates to reflect on a UI as they arrive, without requiring the Consumer to track and confirm that all property values have been received. This aligns better with the flexibility and low-latency benefits of WebSockets compared to HTTP.

The idea of using WebSockets over HTTP stems from the need for responsiveness and event-driven communication, where operations can proceed incrementally, rather than being tightly coupled to a single, aggregated response. This approach supports better scalability and responsiveness in dynamic environments, which seems to align more with the intent of WebSockets.

What are your thoughts on balancing strict conformance with practical efficiency and user experience?

Maybe it makes sense that the consumer is in control how to receive the response, either aggregated or as a stream.

[hspaay]

Adding my 2c's.
I've used both approaches in an earlier iteration. From an implementers point of view I prefer a single way of doing things rather than multiple ways.

I'm concerned that if the property readings are sent individually it might increase implementation complexity for Consumers, since they will have to figure out when they have received all the property readings (which may not be straightforward if there are writeOnly properties or permissions issues). It also means that if we introduce some form of correlation ID (as some people have suggested) to associate responses with requests, there would be multiple responses for a single request.

Yeah this is a very good point. If the consumer has to implement tracking multiple responses to know when a request is complete, it makes things more complicated. For example, dealing with the case where the response stream is never completed. Now you have to add timeouts to 'guess' when things are done. It doesn't get prettier.

To address @benfrancis concern, if the result comes as a stream then I would ask for adding a progress field that indicates if more results are expected or when the stream has been completed. That saves a lot of hassle tracking the completion. In addition, having a requestID/correlationID that links to the request also helps. (I can't live without it actually)

If the progress field is included then either method will be fine IMHO. Without it I'd definitely prefer the single response.