Specify format of additional information for TM-to-TD conversion?

[JKRhb]

Regarding the conversion from TMs to TDs the specification currently states that

Missing communication and/or security metadata details MUST be complemented in the Thing Description instance based on Section § 6.3.4 securityDefinitions and security and/or § 6.3.9 forms.

While there is a defined format for placeholders, there is currently no concrete specification regarding the format in which the additional information should be provided and how it is inserted into the TM. I think it could be useful to at least give some guidance in this regard.

The approach I followed so far was to use two additional files besides the placeholder map. One of these files contains meta-data that complements or overrides the existing meta-data of the TM while the other one provides binding information that is inserted into affordances (if they exist).

Given the (slightly altered) example from the draft...

{
    "@context": [
        "http://www.w3.org/ns/td",
        {
            "saref": "https://w3id.org/saref#"
        }
    ],
    "@type": [
        "tm:ThingModel",
        "saref:LightSwitch"
    ],
    "title": "Lamp Thing Model",
    "description": "Lamp Thing Description Model",
    "properties": {
        "status": {
            "description": "current status of the lamp (on|off)",
            "type": "string",
            "readOnly": true
        }
    },
    "actions": {
        "toggle": {
            "description": "Turn the lamp on or off"
        }
    }
}

... I would add the following meta-data ....

{
    "@context": [{ "@language": "de" }],
    "title": "LED-Steuerung",
    "titles": {
        "de": "LED-Steuerung",
        "en": "LED-Controller"
    },
    "description": "Steuerungseinheit für eine LED",
    "descriptions": {
        "de": "Steuerungseinheit für eine LED",
        "en": "Control unit for an LED"
    }
}

... and bindings as well as security definitions ....

{
    "properties": {
        "status": {
            "forms": [
                {
                    "op": "readproperty",
                    "href": "coap://example.org/led/status",
                    "cov:methodName": "GET"
                }
            ]
        }
    },
    "actions": {
        "toggle": {
            "forms": [
                {
                    "href": "coap://example.org/led/toggle",
                    "cov:methodName": "POST"
                }
            ]
        }
    },
    "security": [
        "nosec_sc"
    ],
    "securityDefinitions": {
        "nosec_sc": {
            "scheme": "nosec"
        }
    }
}

to create this complete TD:

{
    "@context": [
        "http://www.w3.org/ns/td",
        { "@language": "de" }
    ],
    "@type": [
        "Thing",
        "saref:LightSwitch"
    ],
    "title": "LED-Steuerung",
    "titles": {
        "de": "LED-Steuerung",
        "en": "LED-Controller"
    },
    "description": "Steuerungseinheit für eine LED",
    "descriptions": {
        "de": "Steuerungseinheit für eine LED",
        "en": "Control unit for an LED"
    },
    "security": [
        "nosec_sc"
    ],
    "securityDefinitions": {
        "nosec_sc": {
            "scheme": "nosec"
        }
    },
    "properties": {
        "status": {
            "description": "current status of the lamp (on|off)",
            "type": "string",
            "readOnly": true,
            "forms": [
                {
                    "op": "readproperty",
                    "href": "coap://example.org/led/status",
                    "cov:methodName": "GET"
                }
            ]
        }
    },
    "actions": {
        "toggle": {
            "description": "Turn the lamp on or off",
            "forms": [
                {
                    "href": "coap://example.org/led/toggle",
                    "cov:methodName": "POST"
                }
            ]
        }
    }
}

My reason for splitting meta-data and binding/security information was the fact that this approach allows using the same meta-data with different kinds of implementation specific bindings which makes TMs a lot more flexible.

While my approach worked quite well so far, I think there are some aspects that might need some discussion. In which scenarios, for example, should the existing definitions be completely overwritten or only supplemented? In the example above I combined the @context with the additional map containing the language info. Also, should the bindings information be provided in a format like the one above or rather as a map of JSON pointers?

The alternative to specifing these details would be to allow implementers more freedom in how to handle this aspect of the conversion process. However, I think it would be very useful to define standardized formats to allow for an easier re-use of models in different contexts.

[relu91]

While there is a defined format for placeholders, there is currently no concrete specification regarding the format in which the additional information should be provided and how it is inserted into the TM. I think it could be useful to at least give some guidance in this regard.

In my understanding, this part is left open on purpose. As you noted at the bottom of your comment, the current consensus is to leave this aspect of the TM -> TD process open to implementers. We are facing similar issues in the Scripting API where you can instantiate a TD from a Partial TD (e.g. a TD with no forms).

The point is that different tools will have different requirements, consequently different algorithms to achieve the same result. Taking your approach; it works well for human-operated tools or CLIs. but does it work for a runtime that can only support certain types of forms? or that can fill that information automatically? not really. Certainly, we can add some guidance on how a form from a particular binding should look like (https://github.com/w3c/wot-binding-templates/issues/121).

About the metadata part, I wonder if the import or composition of TMs should help there... do we need another file type? 🤔

[egekorkan]

I think that we can only add some tips at this point. If we want something more assertive, we need to postpone this.