Wot-thing-description: Rename / retitle op for Things

[RoboPhred]

The current TD spec currently does not provide any means for renaming a thing, and leaves it up to the implementation to choose a name.

This isn't ideal, as it leaves the configuration of the title up to whatever the implementation wants. This is extremely impractical for home automation, where the only derivable default might be something like "Switch" or "Light", when the user really wants to know what particular switch or light it is (ex: "Kitchen Light"). Such information is only known to the user, and there needs to be a way for the user to teach the Thing what its name is.

Some configurations, like webofthings.io, supply their own http methods for renaming the thing. The Thing Discovery spec seems to have something similar, creating endpoints to modify TDs directly.

It would be great if we could get a Thing-level operation for re-titling.

Alternatives I have considered:

• HTTP PATCH on the thing directly, going outside of the TD bindings.
• Providing a 'name' or 'title' PropertyAffordance, and having my user interface use it over the TD title.
• Having the backend source the TD's title property from a title PropertyAffordance on the thing
• Having a 'rename' ActionAffordance.

[egekorkan]

So all the 3 last points can be done with the current spec but it would be up to the implementation. Do you mean that the TD spec should prescribe how this should be done? If we do so, it can be the default one at best and these other options would be other ways. However, I don't see the benefit of standardizing it in a "MUST" way but a suggestion in the specification would definitely be nice. We can also start thinking of a set of annotations that we encourage people to use when doing something specific, like a renaming action.

My point of view:
Generally, I like considering TDs as mostly static resources so that one can write scripts for them easily, proxy the Things based on TDs, etc. Also, node-wot (which is just 1 implementation), relies on the title field to generate the endpoints, so this would mean reexposing a Thing.

[sebastiankb]

@RoboPhred
What you are requesting is something what you can always do at the application level and has nothing to do with the TD itself. E.g., if a manufacture offers a TD then it may come with some own title pattern like "The XYZ Lamp". In your application you can take over the title, or overlay it with an application specific title like "My Smart Home: XYZ Lamp in Room X". Alternative you can copy the TD of the manufacture and do you own modification in there.

@danielpeintner
I wonder if this topic is more relevant to the WoT API TF.

[RoboPhred]

The reason I asked about this is I was approaching TD as an api for devices that was agnostic to its host or device. My assumption was that I could create a client that speaks only TD and is able to both control and configure devices and device networks.

Does this mean some operations (like renaming) require domain knowledge of the device itself? This would severely hamper interoperability with clients that support any TD source, and would continue to push us down the path of each device or td service requiring its own dedicated app / interface. This would hamper the development and adoption of more general purpose WOT control applications agnostic to the source of the thing.

[lmy441900]

A TD is a _descriptor_ that merely describes a thing, placing no limitation on _how_ the described thing works.

1. By not having a OP like rename, more things can be described, and they _may not_ be renamed. For example, a "brown field" (existing) device that doesn't have a rename API at all, or an extremely resource-constrained device that cannot support rename at all.
2. There are ways to support renaming, e.g. a property thingName, an action rename. Just as Ege said:

So all the 3 last points can be done with the current spec but it would be up to the implementation.

Placing TD fields on the properties / actions can be regarded as an implementation-specific, application-level way to support a "rename" operation. On the other hand, these _operations_ are described in the TD, so no more domain-specific knowledge may be required.

1. There are also ways to do these on the consumer side, as Sebastian said: just modify the saved TD copy. The thing may always carry the same TD, but the client remains free to change the TD wherever it wants (it's just a descriptive document after all).
2. As Sebastian mentioned:

I wonder if this topic is more relevant to the WoT API TF.

If I don't get it wrong, this TF will deliver another specification on the recommended set of APIs (properties and actions) that may be implemented by thing implementors. This will support point 2, and hopefully fulfill your requirement.

[RoboPhred]

Having recommended affordances is exactly the sort of thing I am looking for.

Is there a github repo / TF hub for the API work? The closest I can find is the scripting api but that seems to be defining an api for programming languages to interact with things, rather than defining APIs on things.

[lmy441900]

Is there a github repo / TF hub for the API work?

@RoboPhred I think there isn't one yet.

[egekorkan]

rather than defining APIs on things.

It is also there. What do you need exactly?

[lmy441900]

@egekorkan I think what @RoboPhred wants is another WoT Profile... I don't really understand what "WoT API" means in Sebastian's reply, but it looks like it actually means "WoT Scripting API" rather than some "REST APIs provided by Things".

[egekorkan]

I think a bit more specific than that? If I understand correctly, it is more like a specific REST API for Things. The current HTTP/JSON Profile is just some restrictions but I hope we will never specify a specific REST API in the context of TDs.

[RoboPhred]

Generally, I am after some more standardization on some of the more administrative operations on Things. Something like iotschema, but targeting setup and configuration.

The immediate problem I face is renaming things. I could just roll my own solution, but it would be nice to get greater alignment across implementations. It doesn't need to be a required 'MUST' style definition, but just some spec that multiple implementers could agree on, similar to the Thing Discovery efforts. I thought providing an optional form op would be nice as then implementations could differ, yet still give instructions for consumers to understand how to use their implementation.

Having some metadata or @type annotation on a property or action would be equally ideal though. Some way I can tie the behavior of a property or action to the ability to rename the device, allowing my UI to have a rename feature that works across any implementation that chooses to support it.

[egekorkan]

I think now I understand it and I quite like it. Funny enough, this is actually in the charter of the interest group in some way (https://www.w3.org/2019/10/wot-ig-2019.html) under lifecycle. There it was rather abstract but I think that if we want to keep the spirit of WoT to adapt to any implementation, the way to go in a standardized way would be that we as the WG develop a vocabulary that the implementors can use to annotate operation regarding the management of the Thing. For example, if I include a vocabulary called management under a certain URI in the @context of the TD, I can do annotations like "@type":["rename"] which can be for actions or properties, HTTP or MQTT etc.

Since the TD is something we have invented, we can be more assertive about how this management should be done, rather than saying "Just us a vocabulary that someone has invented", which is what we are doing now. That would be still possible though :)

[danielpeintner]

_Note: I am catching up with reading through GitHub issues so I did probably not read too carefully the entire thread_

@danielpeintner
I wonder if this topic is more relevant to the WoT API TF.

In scripting one can provide a partial TD that gets exposed by a WoT runtime with additional information like bindings information and such.
w.t.r. it is somewhat related. Having said that, scripting still assumes the title to be stable.

I think the general issues here is that there seems to be the assumption that a TD is something one can configure and tweak certain settings, titles shown in UIs etc while a TD is mainly just a _static_ description. One can update the TD with new information but the TD spec itself is not concerned about how changing certain values happens.

[relu91]

Just one side comment adding operation types is not free. It is a modification of the interaction model and therefore puts pressure on both consumer's and producers' implementations. As hinted by @egekorkan I'd be happier if we find a generic operation that can be used to update a Thing Description (not a super tailored operation that just rename it). if you think about it the OP problem is a subset of updating Thing Description metadata (e.g. add other attributes like location). So I think there is room for having a generic operation type.

I also agree with @danielpeintner, therefore we could look to maybe discovery for management and TD lifecycle. We already have update operations in Thing Description Directories and Peer-to-Peer discovery. We could define methods for updating and notifying TDs even in the Peer-to-Peer scenario.

[RoboPhred]

A generic operation would be nice, but there should be a way for the TD to define what TD attributes can be modified. For the use case of renaming, this would control whether the TD consumer / management interface presents a "rename" option to the user. Such an option should not be rendered if the thing does not support renaming. In my setup, some Things just aren't re-nameable, and I would like the UI to reflect this.

For example, a form property called "mutable" which takes attribute names (or maybe json paths for deep mutation).

{
  "forms": [
    {
      "op": "updatedefinition",
      "mutable": ["title", "description"]
    }
  ]
}

Having limitations on what can be modified would also imply that such an operation would be partial: Any attribute not set remains the same. This would probably be better than the alternative where the entire TD has to be sent back, including unmodified attributes.

Would such a TD modifying operation be able to insert new affordances as well? Its an intriguing idea... Since each affordance carries its own forms, it might be feasible to allow a third party to come along and sling a brand new property on top of an already existing Thing. Although that might break down if the thing includes a "readallproperties" or "readmultipleproperties" form.

All things considered, I think I like the Thing Name property / @type IRI (as @egekorkan mentioned) over a TD modifier op, since it solves the question of feature discoverability, but I am open to perusing this thing modification op as well.

[egekorkan]

I feel that this last snippet is leading somewhere interesting. In the discovery spec, the entire TD seems to be updateable but what if it's not the case and the directory and its TDs want to specify what parts can be modified.

[RoboPhred]

This will definitely be the case with my implementation. My TDs are all derived from a hub + plugins that are authoritative thing sources. I didn't intend for clients to be able to submit their own descriptions or modify the descriptions the hub itself generates. Hopefully that is a MAY and not a MUST. I was hoping to use the discovery spec eventually but as an authoritative definition provider rather than a publicly writable address book.

(Edit: Hmm, Directories spec seems to require full mutability at the moment... Made WOT Discovery#208 to track that.

I need to look into discovery more closely some time, but I still have the thorny problem of authorization to get through and the stopgap measure of an api endpoint emitting an array of all things is holding up for now.

[relu91]

Would such a TD modifying operation be able to insert new affordances as well? Its an intriguing idea... Since each affordance carries its own forms, it might be feasible to allow a third party to come along and sling a brand new property on top of an already existing Thing. Although that might break down if the thing includes a "readallproperties" or "readmultipleproperties" form.

Isn't this dangerous? I mean a could add a malicious affordance to one of your thermostats that does bad things or steal information from you. I would constraint the modification to only meta-data no affordances can be added/removed. (I know that the TDD allows for generic modifications but there the use case is different: it is the device that updates its own description).

[FadySalama]

I would be very cautious about adding operations that allows third parties to modify the TDs in any way. As @relu91 said, it's quite dangerous and opens a possible security vulnerability. A Thing should be really the only source-of-truth regarding the capabilities it wants to expose.
Allowing third parties to modify the TDs, even simple metadata, adds a lot of overhead. Modifications need to be tracked, and consumers cannot rely on caching the TD. Modifying affordances can break applications, and consumers would need to either be notified if such a breaking change occurs or need to verify it themselves.

[egekorkan]

In the call of 21.07 we have talked about:

• The use case is not exactly clear
• The notion of dynamic TDs causes issues for Consumers in a system
• A way to do this without using a TD Directory can be explored by the Discovery specification
• The discussions are deferred for another call