Combine properties into a single things property

[benfrancis]

This PR proposes combining the current retrieveTD, retrieveTDs, searchJSONPath and searchXPath properties in the example Thing Description of a Thing Directory into a single things property.

The rationale is discussed at length in #133 but the main reason is that property names should not contain verbs. A single things property seems to be the best way to model the collection of Thing Descriptions in the Directory's Thing Description.

A sparql property is kept separate from the things property due to the needs of conforming with the SPARQL specification, which mandates a particular URL structure and HTTP verbs.

---

Preview | Diff

[mmccool]

IMO: This has similar usability problems as with the PUT/PATCH merger mentioned in the PR #160 - it may be more RESTful, but is also now more protocol specific and harder to use. I personally think the original design with a separate named interaction for each distinct operation is better... and then we won't have an exception for SPARQL.

[benfrancis]

@mmccool: Thanks for the feedback.

1. The current property names contain verbs, do you think that's OK? If not, then what should they be renamed to?
2. What "operation" (op) does each interaction represent? From the currently defined available options they all look like readproperty to me, hence merging them into one interaction affordance.

I agree that this Thing Description is non-trivial for Consumers to use, but I'd suggest that's more of a result of the fact that Thing Descriptions do not have a way of modelling collections of resources than because it's more RESTful. Thing Descriptions are unfortunately just not well suited to describing this kind of API (as compared with something like OpenAPI for example).

The re-design was intentionally more RESTful and protocol specific, because it's describing a REST API over HTTP.

Although I disagree that non-web protocols like MQTT should be in scope for the Web of Things, I can see why people would want to communicate with an IoT device using MQTT. I can not see why they would want to browse a directory of things over MQTT however. Does someone have a use case for that?

[farshidtz]

Although I disagree that non-web protocols like MQTT should be in scope for the Web of Things, I can see why people would want to communicate with an IoT device using MQTT. I can not see why they would want to browse a directory of things over MQTT however. Does someone have a use case for that?

You are right; MQTT is not suitable for browsing TDs stored in a directory. But MQTT brokers have other features to support that and it could be between clients and the broker (no directory involvement).

[mmccool]

So I had some additional thoughts on this. If each distinct function can be distinguished by an interaction/op pair then it should still be relatively easy to use from the scripting API. But I think it would be an anti pattern to overload a single interaction so much that the user needs something other than this to select a "function". In particular there is no easy way to select among forms in a single interaction with the same op, and URLs are supposed to be "under" the abstraction, so manipulating them is not reasonable or good practice/feasible. The trouble is, I think the RESTful design guidelines assume you are working with URLs directly...

Consolidation may still make sense, but let's not go too far.

Regarding names, e.g. verbs vs nouns, I do think that if the "natural" name for an interaction is a verb that you should consider carefully whether it makes sense for it to be a property (for instance).

[benfrancis]

See #172 for an alternative proposal

[farshidtz]

@benfrancis could you please also separate the renaming and merging into different PRs? Otherwise, we won't be able to get consistent names in the refactor branch and merge the first set of changes into main until this discussion is concluded.

Properties could be (for now):

• thing
• things
• jsonpath
• xpath
• sparql

Overall, I propose doing all the renamings and semantic annotations in a single PR (maybe in #160) because they don't make sense independently.

[mmccool]

discussion:

• when is something an action?
• pragmatically: things property; separate "query" affordances; classify as "actions" anything that has an input different from the output; then pick appropriate names (verbs or nouns as appropriate...)
• but... we also don't want to make MAJOR changes at this point (no time...)

[benfrancis]

Superseded by #184