Wot-thing-description: TDT shall allow to define placeholders

[sebastiankb]

TDT should include a placeholder feature. The placeholder shall be substituted when a concrete TD instance is generated. E.g.:

TDT may contain:

"title":"Sensor Nr-{{DEVICENUMBER}}"

A corresponding instance will replace {{DEVICENUMBER}} by the value 2:

"title":"Device Nr-2"

I'm quite open about the placeholder pattern.

[sebastiankb]

This feature can be also used to point out the underlying protocol that is used by a Thing. E.g.,

"base":"mqtt://{{BROKERADDRESS}}"

[relu91]

Thumb up for the placeholder pattern; libraries like handlebars and mustache can handle the processing of these placeholders out of the box.

[sebastiankb]

Thanks for sharing the links. Do you aware of some standards which we can refer to?

[relu91]

I did a little bit of research and it seems that there is no consensus on a standard text templating language. Here I found a table comparison of the most known. Mustache is well supported across many coding languages but it lacks inheritance and assignments features. Its template syntax is very minimal and it is specified here. Even Wikipedia uses similar syntax, although it extends the basic capabilities.

Liquid is also another well-adopted option and it is used inside Jekyll.

Finally, it may be worth to specify the level of expressiveness that we want from the placeholders inside of a TDT and then choose the appropriate templating lang (if it exists).

[benfrancis]

With the caveat that I still haven't seen compelling evidence that Thing Description Templates are actually needed, RFC 6570 may be useful here. It was designed for URIs rather than arbitrary strings, but it defines a standard template syntax.

[sebastiankb]

Thanks for the hint. TD spec already use it for the uriVariables.

[egekorkan]

Thanks for the hint. TD spec already use it for the uriVariables.

Having said that, maybe we can experiment on using URI templates for uri elements that are not query parameters. This would already possible for the example "base":"mqtt://{{BROKERADDRESS}}" above. However, this would not fix using such templates in any string (like title, description etc.).
Note: Since the TD specification says Values that are of type string or anyURI MUST be serialized as JSON strings., we cannot say that placeholders must be denoted by something like reverse slash, i.e. \ according to JSON specification. Curly brackets are totally fine :)

[sebastiankb]

I'm not sure I understood your point, why this should not work for the title, etc.. base and href are also string/anyURI based.
In general, in TDT will have different kind of rules compared for TD instances. E.g., TDT will not follow what is mandatory in a TD instance (e.g. forms).

[egekorkan]

Having said that, maybe we can experiment on using URI templates for uri elements that are not query parameters. This would already possible for the example "base":"mqtt://{{BROKERADDRESS}}" above.

I think I don't remember the exact reasoning I had 10 days ago but basically what I meant is that we are currently using uriVariables for query parameters but it should be possible to use them for non query parameter parts of a URI.

However, this would not fix using such templates in any string (like title, description etc.).

I am not sure if URI templates are used for strings that are not URIs. They can be I guess?

If you are asking about my note, we should simply pay attention to not define a mechanism that will not work with JSON.

[sebastiankb]

"title":"Sensor Nr-{DEVICENUMBER}" is a valid JSON String. A TDT processor has to identify this placeholder. But the problem I see is that curly brackets are sometime supposed to be used in the string. How we going to distinguish that?

[sebastiankb]

Angular seems to use the {{...}} approach.

[sebastiankb]

and VueJS

[takuki]

It may be a good practice to declare all the variable names up front in the TDT so that it is clear what variables need to be filled in to make a concrete TD, without first parsing the whole TDT.

[takuki]

In May 8th TD telecon, @mlagally volunteered to explain how Oracle is defining device models.

[takuki]

In May 22th TD telecon, @sebastiankb mentioned "constructor" approach discussed in WISHI call. @sebastiankb will describe more on that idea.

[sebastiankb]

Here are the slides presented by @cabo

It is mentioned that in a TDT there should be something like a constructor which can be used to initiate some specific parameters to initiate a Thing. I think the placeholder approach presented in this issue can also be seen as a constructor where all placeholder variables must be initiated when it comes to TD instantiation.

@cabo what do you think about this?

[takuki]

Note: Since the TD specification says Values that are of type string or anyURI MUST be serialized as JSON strings., we cannot say that placeholders must be denoted by something like reverse slash, i.e. \ according to JSON specification. Curly brackets are totally fine :)

Can we say "all values that are of type string or anyURI" in TDT are subject to URI Template (RFC 6570) processing during TD instantiation?

On the other hand, for TD instances we can control the number of places where such template can still be used.

[egekorkan]

Another related issue from w3c/wot https://github.com/w3c/wot/issues/284

[fennibay]

With the caveat that I still haven't seen compelling evidence that Thing Description Templates are actually needed

I believe this is important. IMHO Thing Model (#930) is definitely needed for the reasons listed in w3c/wot-architecture#458, but TDT probably not anymore. I tried to think of scenarios where TDTs may still be used after the introduction of Thing Models (TMs):

Scenario 1: A thing manufacturer instantiates TDs out of TDTs. Here the address, name, serial number etc. are filled out. Consumer uses the TDs, doesn't see TDTs. They may also use the related TMs.

Scenario 2: A thing manufacturer has a family of related models. There is a TDT for the whole family. TDT for a single model can be created from the family TDT. The TDs for the instances are then created like in scenario 1. Consumer uses the TDs, doesn't see the TDTs. They may also use the related TMs.

Scenario 3: There is an intermediary party who provides an engineering/configuration software to build a solution consisting of things provided from multiple manufacturers. In the solution things are configured and assembled together. The consumer will then access the TDs of the things in this solution.

• In this scenario the TDTs could be shared by the manufacturer to the intermediary, along with rules on how to create TDs from the TDTs. This is the only case where multiple parties are involved with TDTs, but I believe it's not a good design.
• From encapsulation POV, I think it would be better if the manufacturer provided a configuration interface to the intermediary party, that also isolates the details about how a TD is instantiated.

So, with the introduction TM, TDT becomes solely a manufacturer-local aspect, hence doesn't need standardization.

And this way we don't have to dictate how the solution for TDT should look like. It doesn't have to always be placeholder-based. It could also be model/rule-driven, generated by custom software, handwritten etc. But manufacturer can locally decide how they solve it.

[egekorkan]

By the way, OpenAPI uses single curly brackets:

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

[sebastiankb]

I think using double curly brackets would help to distinguish between RFC 6570 pattern in URLs, right?

[egekorkan]

In the call of 12.05.2021, we have decided to close this issue