Re: [core] [T2TRG] Review of CoRAL

[Frank MATTHIAS KOVATSCH <[e-mail]>]

Dear lists,
dear Klaus

Here are some thoughts on hypermedia, in particular the form concept, from an originally internal discussion with Klaus to align CoRAL and WoT TD.

So far, we agree that forms should be comprised of:
* form context (on what is the operation performed)
* operation type (identifier for the operation analogous to rel of links)
* submission Target (target URI for the request)
* optionally, form fields (additional parts of the request pre-set by the server)

It should be pointed out that the form fields are not like the inputs of HTML forms to define the payload, but may apply to any part of the request. A use case for TD forms is CoAP options that have to be set for certain servers (e.g., OCF devices). In general, forms are really like printed forms at some agency: the creator (server) prefills some parts according to its process and leaves some parts open to be filled by the client. Going back to protocol messages, forms are basically request templates, and we have to decide which fields must always be there to make a valid request.

I think the _request method_ should also be mandatory. For me, it is the central reason to introduce forms, because so far servers have not been able to directly tell clients what method is expected; it has always been defined out-of-band, e.g., as part of media type definitions or using the OPTIONS method (however without a mapping to what they do).
However, the available set of methods depends on the protocol. Thus, the request method field is actually protocol-dependent, which is why TD makes the field name also protocol-dependent ("http:method", "coap:method", ...) -- true there is an overlap between HTTP and CoAP, but the values come from a different domain. This would be an argument to put these fields under the open-ended form fields.

The _submission type_ to define the payload format is definitely important, but not required when there is no payload. This makes it hard to decide whether it should be an explicit field or just be part of the open-ended form fields. I tend more to conditionally mandatory field.

Mandatory does not necessarily mean the fields must always be serialized. Since the operation type must be understood by clients, I could imagine that its definition may include default values for fields that are not serialized. Overall, this is just an optimization to transmit less -- the information must still go into the request.


Looking a lot at RFC 8288 for the definition of forms, I noticed quite a mess around URI vs IRI. Context and target are defined as IRI that in most cases are also URIs, because protocol limitations. But then for the Extension Relation Types, RFC 8288 only talks about URIs (https://tools.ietf.org/html/rfc8288#section-2.1.2), although this is the place where we actually only need a unique string. Maybe this is a lost battle anyway, since elsewhere they are URLs...

CoRAL tries to minimize the processing of IRI/URIs by clients. Ideally, they are just some bytes that are defined by the server and the client has to echo them, so that the (stateless) server can do the right thing. So the encoding of URIs in CoRAL is close to its representation in CoAP options. Yet the client still has to somehow put it into the request. Usually that part of the client logic is forced to use the API of the CoAP library used. In my implementations, I thought it would be good for the developer to make it as close to HTTP libraries as possible, which means that they basically handle strings with all the weird URI magic, disallowing a clean copy from hypermedia control to request.

Klaus, please free to add points that I might have forgotten in my summary!

Kind regards,
Matthias