Compile proposal for URI Templates

[mkovatsc]

With the DataSchema we can currently describe payloads. Many existing APIs also take parameters in the URI (e.g., the query), which would, for instance, be part of Action arguments.

We should include a mechanism similar to DataSchema to describe URI Template parameters, when href contains such a URI Template.

[mkovatsc]

Strawman example with a for a uriSchema field for my Nabaztag with its browser-target HTTP API (all GETs):

    {
      "@type": ["Action"],
      "name": "LeftDown",
      "uriSchema": {
        "p" : { "type": "integer", "minimum": 0, "maximum": 16, "@type": "example:SomeKindOfAngle" },
        "d" : { "type": "integer", "minimum": 0, "maximum": 1, "@type": "example:Direction" }
        }
      },
      "form": [{
        "http:method": "GET",
        "href" : "http://192.168.1.25/left{?p,d}"
      }]
    }

[mjkoster]

This looks good to me. Another reason to have a dataSchema element in all cases (one of dataSchema, inputSchema, outputSchema) to keep it separate from the uriSchema element.

So in the case of the simple TD it could be

"actions": {
  "turnon": {
    "@type": "iot:switchOnAction",
    "uriParameters": {
      "on": {"type": "boolean", "@type": "iot:binarySwitchData", "value": true}
    },
    "form":[{
      "href": "http://10.0.0.1/switch{?on},
      "http:method": "GET",
      "rel": "invokeAction",
    }]
  },
  "turnoff": {
    "@type": "iot:switchOffAction",
    "uriParameters": {
      "on": {"type": "boolean", "@type": "iot:binarySwitchData", "value": false}
    },
    "form":[{
      "href": "http://10.0.0.1/switch{?on},
      "http:method": "GET",
      "rel": "invokeAction",
    }]
  }
}

[mjkoster]

Of course it is understood that the string serialization of the instance described by the schema is to be URI-encoded, e.g. "true", "false", "1234" as string values and % encoded where needed e.g. GET http://10.0.0.1/switch?on=false

[mkovatsc]

Just a note: @mjkoster your example is a bit overengineered by using a schema to fill in a constant -- you could just put the constant into href without using templates :)

[mkovatsc]

I include your point that the field with the URI template variables is not a schema directly. We again have a naming issue for the term: RFC 6570 talks about "variables", so uriVariables? uriTemplate would be good to also indicate href does not have a simple URI.

BTW: I thought about integrating this into the input field and let the binding take out all properties that have a name used in the URI template, but we then end up with an issue for the template: is the remainder a simple value or an object when only one data item is left? It might need a wrapper, which is then similar to this in complexity.

Here is an updated sample:

  "actions": {
    "LeftDown": {
      "uriVariables": {
        "p" : { "type": "integer", "minimum": 0, "maximum": 16, "@type": "example:SomeKindOfAngle" },
        "d" : { "type": "integer", "minimum": 0, "maximum": 1, "@type": "example:Direction" },
        }
      },
      "form": [{
        "http:method": "GET",
        "href" : "http://192.168.1.25/left{?p,d}"
      }]
    }
  }

@vcharpenay could you please review in terms of JSON-LD correctness? @sebastiankb we need to integrate this into the TD spec before TPAC.

[sebastiankb]

Yes, I agree to have something for TPAC on the table. Until Friday, I try to have a first draft.

[mkovatsc]

See https://tools.ietf.org/html/rfc6570 for the URI Template syntax.

[takuki]

On October 25th during Lyon F2F meeting, it was noted that both LwM2M and SmartThings API use URI parameters to carry data in requests, and the group agreed to include this feature in TD. More discussion needs to be done to decide the actual mechanisms.

[takuki]

@sebastiankb , can you make a draft with a concrete example so that we can discuss to improve to make it into the TD spec?

[egekorkan]

This issue is continuing in issue #63 since it is done in the TD spec already. We just need to include it here.