UriVariables can't be used for RootForms

[thjaeckle]

Hi.

I just found out that uriVariables can currently only be defined in InteractionAffordances.
That rules out using them for "RootForms" - which also is defined in the JsonSchema:

• property_element:

  wot-thing-description/validation/td-json-schema-validation.json

  Lines 536 to 541 in 9db5e96

  	"uriVariables": {
  	"type": "object",
  	"additionalProperties": {
  	"$ref": "#/definitions/dataSchema"
  	}
  	},

• action_element:

  wot-thing-description/validation/td-json-schema-validation.json

  Lines 652 to 657 in 9db5e96

  	"uriVariables": {
  	"type": "object",
  	"additionalProperties": {
  	"$ref": "#/definitions/dataSchema"
  	}
  	},

• event_element:

  wot-thing-description/validation/td-json-schema-validation.json

  Lines 701 to 706 in 9db5e96

  	"uriVariables": {
  	"type": "object",
  	"additionalProperties": {
  	"$ref": "#/definitions/dataSchema"
  	}
  	},

I wonder if this is an explicit decision or if this just was not yet thought about.
Using uriVariables in root forms might become really useful, e.g. in order to define which fields to select for the readmultipleproperties OP, e.g.:

{
    "@context": [ "https://www.w3.org/2022/wot/td/v1.1" ],
    "security": "basic_sc",
    "id": "urn:de.jaeckles.test:the-thing-1",
    "base": "http://localhost:8080/api/2/things/de.jaeckles.test:the-thing-1",
    "securityDefinitions": {
        "basic_sc": {
            "in": "header",
            "scheme": "basic"
        }
    },
    "uriVariables": {
        "fields": {
            "type": "string",
            "title": "Comma separated list of properties to select."
        }
    },
    "forms": [
        {
            "op": "readallproperties",
            "href": "/attributes",
            "htv:methodName": "GET"
        },
        {
            "op": "writeallproperties",
            "href": "/attributes",
            "htv:methodName": "PUT"
        },
        {
            "op": "readmultipleproperties",
            "href": "/attributes{?fields}",
            "htv:methodName": "GET"
        },
        {
            "op": "writemultipleproperties",
            "href": "/attributes",
            "htv:methodName": "PATCH",
            "contentType": "application/merge-patch+json"
        },
        {
            "op": [
                "observeallproperties",
                "unobserveallproperties"
            ],
            "href": "/attributes",
            "htv:methodName": "GET",
            "subprotocol": "sse",
            "contentType": "text/event-stream"
        }
    ],
...

Which could be usable as:

GET http://localhost:8080/api/2/things/de.jaeckles.test:the-thing-1/attributes?fields=location,manufacturer

[benfrancis]

Nice catch, I've never noticed this.

This also makes me curious why uriVariables is a member of InteractionAffordance rather than a member of Form. Is it so that uriVariables can theoretically be shared by multiple forms?

[thjaeckle]

I think the uriVariables should be defined on TD top level next to and similar to schemaDefinitions.

The securityDefinitions are referenced only from additionalResponses in Form elements. Being on top level they can however also be used in root forms as well.

[relu91]

This also makes me curious why uriVariables is a member of InteractionAffordance rather than a member of Form. Is it so that uriVariables can theoretically be shared by multiple forms?

This is a good point, I think they were originally assigned the InteractionAffordance class because they were thought to be additional input parameters in the WoT Interaction Model. I remember people reporting use cases for having the ability to use UriVariables for reading properties (which in the abstract interaction model does not have any input). However, for their protocol-related nature, they should be really inside a Form and maybe as @thjaeckle in a root object for easy reuse.

I would be happy also to see mechanisms to map Action inputs to specific UriVariables so that we have a clear separation between logical inputs of an Affordance and protocol level payloads.

[sebastiankb]

from today's TD call:

• it would be consistent to have uriVariables at the top level for forms similar we have at interaction level
• it seems realistic to cover this feature also for TD 1.1
• lets decide next week

[sebastiankb]

from today's TD call:

• group decided to introduce uriVariables at the top level
• this has also the benefit that global-based uriVariables definitions can be made that are valid for local interactions forms