Proposal: Manageable actions and data mapping using semantic annotations

[benfrancis]

Before we take the first step on the slippery slope of turning Thing Descriptions into a turing complete programming language by adding "variables" as a top level member of Thing Descriptions, I wanted to re-visit an old idea of using semantic annotations to describe dynamic resources in a declarative way.

What if we created a semantic context that defined some special terms that can be used in data schemas (including URI variables) to explain their semantic meaning in the context of the WoT information model?

Specifically, I'm thinking about terms such as:

• wot:propertyName
• wot:propertyValue
• wot:actionName
• wot:actionInput
• wot:actionOutput
• wot:actionStatus
• wot:actionID
• wot:eventName
• wot:eventData

To make this work I would also suggest adding a status member to ActionAffordance as per @relu91's suggestion in #2068.

These special semantic annotations could be used to specify particular URI variables and specific members of data payloads as action IDs, and also point to which part of an action status is its output.

In more complicated bindings with data wrappers in their payloads they may also be used to point out which part of a payload is the actual value of a property or data from an event, and potentially also details like how to enumerate property names in a readmultipleproperties request.

Below I have provided an example which attempts to solve the long term problem of how to describe the HTTP Basic Profile protocol bindings (particularly the action protocol bindings) declaratively in a Thing Description!

{
  "@context": [
    "https://www.w3.org/ns/wot-next/td",
    "wot": "https://www.w3.org/ns/wot-next/"
  ],
  "id": "https://mywebthingserver.com/things/lamp",
  "base": "https://mywebthingserver.com/things/lamp/",
  "title": "My Lamp",
  "description": "A web connected lamp",
  "securityDefinitions": {
    "oauth2": {
      "scheme": "oauth2",
      "flow": "code",
      "authorization": "https://mywebthingserver.com/oauth/authorize",
      "token": "https://mywebthingserver.com/oauth/token"
    }
  },
  "schemaDefinitions": {
    "error": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "status": {
          "type": "number"
        },
        "detail": {
          "type": "string"
        },
        "instance": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "actionStatus": { 
      "@type": "wot:actionStatus",
	  "type": "object",
	  "properties": {
	    "state": {
	      "type": "string",
		  "emum": ["pending", "running", "completed", "failed"]
		},
		"output": {
		  "@type": "wot:actionOutput"
		},
		"error": {
		  "$ref": "#/schemaDefinitions/error"
		},
		"href": {
		  "@type": "wot:actionID",
                  "type": "string"
		},
		"timeRequested": {
		  "type": "string",
		  "format": "date-time"
		},
		"timeEnded": {
		  "type": "string",
		  "format": "date-time"
		}
	  }
	},
	"actionStatuses": {
	  "type": "object",
	  "propertyNames": {
	    "type": "string",
	    "@type": "wot:actionName"
	  },
	  "additionalProperties": {
	    "type": "array",
	    "items": {
	      "$ref": "#/schemaDefinitions/actionStatus"
	    }
	  }
	}
  },
  "security": "oauth2",
  "properties": {
    "on": {
      "type": "boolean",
      "title": "On/Off",
      "description": "Whether the lamp is turned on",
      "forms": [{"href": "properties/on"}]
    },
    "level" : {
      "type": "integer",
      "title": "Brightness",
      "description": "The level of light from 0-100",
      "unit": "percent",
      "minimum" : 0,
      "maximum" : 100,
      "forms": [{"href": "properties/level"}]
    }
  },
  "actions": {
    "fade": {
      "title": "Fade",
      "description": "Fade the lamp to a given level",
      "synchronous": false,
      "input": {
        "type": "object",
        "properties": {
          "level": {
            "title": "Brightness",
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "unit": "percent"
          },
          "duration": {
            "title": "Duration",
            "type": "integer",
            "minimum": 0,
            "unit": "milliseconds"
          }
        }
      },
      "status": {
        "schema": "actionStatus"
      },
      "uriVariables": {
        "actionID": {
          "type": "string",
          "@type": "wot:actionID"
        }
      },
      "forms": [
        {
          "href": "actions/fade",
          "op": "invokeaction"
        },
        {
          "href": "{actionID}",
          "op": "queryaction"
        },
        {
          "href": "{actionID}",
          "op": "cancelaction"
        }
      ],
    }
  },
  "forms": [
    {
      "op": ["readallproperties", "writemultipleproperties"],
      "href": "properties"
    },
    {
      "op": "queryallactions",
      "href": "actions",
      "additionalResponses": [{
        "success": "true",
        "schema": "actionStatuses"
      }]
    }
  ]
}

This example makes use of JSON pointers (I hope I got that part right!) assumes that a queryaction request and an invokeaction request for an asynchronous action would get a response according to the status data schema. It also uses additionalResponses to define a data schema for the queryallactions operation which is a bit of a hack, but I'm hoping we might come up with something cleaner than that for TD 2.0. It also assumes default HTTP verbs for queryaction (GET), cancelaction (DELETE) and queryallactions (GET).

Please let me know what you think.

P.S. If we were very brave we might even consider defining the data schemas from schemaDefinitions as default data schemas for the queryaction and queryallactions operations in the HTTP Binding for if a TD doesn't specify something itself. That would make TDs using future HTTP-based Profiles much cleaner!

[danielpeintner]

Thank you, @benfrancis, for your proposal that brings one far.

Anyhow, I would like to list some topics that come to my mind (maybe because I misunderstand some parts) and I am pretty sure I miss other aspects:

• the term status implicitly maps to the form with "op": "queryaction", correct? Could it be that cancelaction returns data also, and we might need something similar?
• What if queryaction/cancelaction requires actionID in some other form? Not in the URL, but let's say in the body or so? Can we describe it?
• How do I know which actionID has the action I kicked of? Is it described somewhere how I get this information?

Thanks!

[benfrancis]

@danielpeintner wrote:

the term status implicitly maps to the form with "op": "queryaction", correct?

Correct, and also somehow needs to map onto queryallactions, which this example does but not in a very neat way (I think we need to revisit how data schemas are defined for all meta operations).

Could it be that cancelaction returns data also, and we might need something similar?

Potentially, I haven't come across that before but it's certainly possible.

What if queryaction/cancelaction requires actionID in some other form? Not in the URL, but let's say in the body or so? Can we describe it?

In general I think this semantic annotations approach is very flexible in that it can be used anywhere in any data schema (including but not limited to uriVariables). E.g. You can specify a particular member of a JSON payload as being an actionID or an actionOutput or a propertyValue. However, this only works if there is a data schema to apply the annotation to...

There is currently no separate data schema for queryaction or cancelaction requests, in the same way that there is no separate data schema for:

• readproperty requests (separate to responses)
• writeproperty responses (separate to requests)
• cancelaction responses (see above)
• observeproperty or unobserveproperty requests
• observeproperty or unobserveproperty responses (separate to individual property readings)
• subscribeevent or unsubscribevent responses (separate to individual event instances)
• Any of the meta operations...

It is difficult to know where to stop.

In the case of responses you can kind of work around this with an AdditionalExpectedResponse, but as far as I know there's no equivalent for requests.

How do I know which actionID has the action I kicked of? Is it described somewhere how I get this information?

In this example Thing Description the actionID is returned as part of the actionStatus schema in response to an asynchronous invokeaction request. See the note: "assumes that a queryaction request and an invokeaction request for an asynchronous action would get a response according to the status data schema".

There would also need to be an assertion somewhere that explains that any actionID provided in an invokeaction request or response should then be re-used in a queryaction request to query that specific action instance.

[danielpeintner]

How do I know which actionID has the action I kicked of? Is it described somewhere how I get this information?

In this example Thing Description the actionID is returned as part of the actionStatus schema in response to an asynchronous invokeaction request. See the note: "assumes that a queryaction request and an invokeaction request for an asynchronous action would get a response according to the status data schema".

Mhh, I think I'm beginning to understand.
My initial thinking was it is a chicken egg problem.

For calling the op queryaction I need the actionID already (see "href": "actions/fade/${actionID}").
If I get your response right, the first call of invokeaction reports actionStatus also...

[benfrancis]

If I get your response right, the first call of invokeaction reports actionStatus also...

That's correct, see Example 16 in Asynchronous Action Response in the HTTP Basic Profile:

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: /things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655
{
  "status": "pending",
  "href": "/things/lamp/actions/fade/123e4567-e89b-12d3-a456-426655",
  "timeRequested": "2021-11-10T11:43:19.135Z"
}

You'll notice that in the above example the URI of the action instance (which identifies it) is also included in a Location header in the response. Assuming that the ResponseHeader class from the HTTP Vocabulary in RDF 1.0 specification can be used, it might be possible to describe this in a Thing Description but it's a bit tricky:

      "forms": [
        {
          "href": "actions/fade",
          "op": "invokeaction",
          "htv:headers": [
            {
              "@type": ["htv:ResponseHeader", "wot:actionID"],
              "htv:fieldName": "Location",
              "htv:fieldValue": "{actionID}"
            }
          ]
        },
        {
          "href": "{actionID}",
          "op": "queryaction"
        },
        {
          "href": "{actionID}",
          "op": "cancelaction"
        }
      ],

(Actually that made me realise that my example TD I was using actionID inconsistently because in some cases it was describing just the UUID part, but sometimes it was a relative or absolute path. I've updated the original example to always use the URI provided in the invokeaction response which would be an absolute path.)

[relu91]

The only problem that I have here is that this mechanism is very bound to the current interaction model, and it cannot capture future extensions without adding new keywords to the spec.

[benfrancis]

@relu91 wrote:

The only problem that I have here is that this mechanism is very bound to the current interaction model, and it cannot capture future extensions without adding new keywords to the spec.

This is true, although if if we change the interaction model we surely have to modify the corresponding ontologies anyway so I don't necessarily see that as a problem.

To be honest I don't love this solution myself because it requires assigning special meaning to certain semantic annotations which Consumers then need to be programmed to understand. It would be far simpler to just define all of this as a prescriptive sub-protocol specification.

However, if we want to enforce the principle that Profiles must not define prescriptive protocol bindings that can not also be described using declarative protocol binding vocabularies in a Thing Description, then we have to find a way to express all of these complicated concepts in a declarative way (even if Profile conformant Things and Consumers don't actually use it).

If we're going to do that then I would personally prefer to try to define the simplest declarative approach we can think of that solves the specific use cases we know need solving within the context of the established WoT information model, rather than a general purpose model for describing a general purpose "stateful runtime context" for Consumers. However, I remain open minded as to other potential solutions.