Re: [core] [T2TRG] Review of CoRAL

[Klaus Hartke <[e-mail]>]

Hej Christian,

thanks a lot for this very detailed review! You're making a lot of
good points. Since several points seem to me worth a discussion on
their own, I will go through the list in the upcoming days one-by-one
and comment on them individually.

A question to the chairs of T2TRG and CoRE WG as this thread was
started on both mailing lists: Where would you like to see the
extended discussion to happen?

Best regards,
Klaus


Christian Amsüss wrote:
> Hello CoRAL observers,
>
> I've read and partially implemented draft-hartke-t2trg-coral-05, and
> would like to offer a review of it.
>
> My two largest individual issues with this are that I'm not convinced of
> the necessity or suitability of the textual format, and that I don't see
> yet how forms would be used in practice (that's out of scope for the
> document, but limits the depth of my review).
>
> In general, the described format would be useful to me, both for new
> applications and to fill in for link-format where RFC6690 is too
> limited.
>
> The following is a rather unsorted list of things that struck me as
> unclear or odd; none of them should stand in the way of a research or
> working group adoption or be otherwise insurmountable; many are also
> just editorial comments.
>
> * "The CoRAL data and interaction model is a superset of the Web Linking
>   model" / "can describe simple resource metadata in a way similar to
>   the Resource Description Framework (RDF)":
>
>   From the examples in 2.1 (in particular, because the rel becomes a
>   full URI), it appears the othr way round: That the data model is a
>   superset of the RDF model, and that the document describes an
>   equivalence of a subset of RDF statements to typed links (as used in
>   link headers, link format and HTML).
>
> * Browsing context: This growing history appears hard to do in a
>   constrained context. Can an agent still work with any given maximum
>   history length, in particular 1 or even 0?
>
> * Forms: I haven't followed all the W3C & surroundings discussions on
>   forms, so I can't say much there as I don't yet understand how they
>   were to actually work. Examples that go beyond "POST to create" and
>   "DELETE to delete" would be helpful when they'd go beyond the
>   intuitive. -- But I assume that as this matures, any formative github
>   discussions will evolve into referrable documents.
>
> * If the first use of the http://www.iana.org/assingments/relation/
>   prefix for rel values pointed to RFC4287, it would be clearer to the
>   reader that this is already established practice.
>
> * Representations: I think it would be helpful to state something in the
>   area of the second paragraph along the lines of "The producer of the
>   CoRAL document claims that the embedded representation is fresh at
>   least for as long as the CoRAL document is fresh", if so intended.
>
>   It's obvious that the "full, partial or inconsistent" part is
>   intentionally giving much leeway to the CoRAL producer. Could this
>   possibly be narrowed down for resources under the same authority? A
>   statement like "(under some condition), the presence of a
>   representation states that there exists a request to the target that
>   would result in a response with the given payload" could go into a
>   direction where an agent could populate its own cache with it and work
>   on from there.
>
> * Binary data format: When relations expressed as uint are first
>   mentioned (and possibly also with numeric form-field-name), a forward
>   reference to the topic of profiles would be helpful.
>
> * Textual format: I find this more confusing than helpful. The format is
>   too far from turtle to allow intuition to be taken from there
>   (especially as there are simple and qualified names, where turtle has
>   only qualified names but the qualifier may be empty), too far from the
>   binary representation to help understanding the binary format (eg.
>   someone only editing in text format would not see that naming a
>   resource linked as rel="index" <index> would be beneficial, but could
>   be misled to believe that application/octet-stream can be a compact
>   default or that representations can have more attributes -- plus
>   people were led to think that CoRAL is large on the wire).
>
>   My impression is that CoRAL would not be written by humans, let alone
>   stored or transported as that. I think the document would be better
>   off if no textual format were defined, but full turtle (or a slim
>   superset thereof that's still within N3) were used to express the
>   semantics of a document (which would need an RDF serialization of
>   forms and representations, but that's more of a benefit than a
>   downside IMO).
>
>   Concrete example from 2.1:
>
>     @prefix : <http://www.iana.org/assignments/relation/> .
>
>     <> :next <./chapter4>;
>        :icon </favicon.png>;
>        :license <http://creativecommons.org/licenses/by/4.0/>.
>
>   or from 2.2:
>
>     @prefix : <http://example.org/vocabulary#> .
>     @prefix coral: <urn:ietf:rfc:XXXX#> .
>
>     <> :task [ = </tasks/1>;
>          :description "Pick up the kids"
>       ];
>       :task [ = </tasks/2>;
>          :description "Return the books to the library";
>          coral:delete [ form:method coap:DELETE;
>                         form:iri </tasks/2>
>                       ]
>       ]
>
> * Why is <http://TBD/> used for attrs, but <urn:ietf:rfc:XXXX#...> used
>   for the core form relations? They could at least share structural
>   similarity.
>
> * attrs: title and title* are described as target attributes in RFC8288
>   and can thus easily occur in CoRAL documents.
>
> * ibd: Then, it can say something like "MUST NOT occur in a CoRAL
>   document as attributes, but are expressed as link relations, nested
>   links and link relations, respectively" to indicate that their
>   information is not lost in the transition.
>
> * Any test vectors or examples to get started on the binary format would
>   be helpful, and could be augmented by (CDDL automatically?) annotated
>   extended diagnostic notation, like (as in the above, assuming a
>   navigation profile where someone forgot that favicon is a typical rel)
>
>   [[/link/ 2, /rel:next/ 4,
>     /<./chapter4>/ [6, "chapter4"]],
>    [/link/ 2, "http://www.iana.org/assignments/relation/icon",
>     /</favicon.png>/ [5, 0, 6, "favicon.png"]],
>    [/link/ 2, /rel:license/ 10,
>     /<http://creativecommons.org/licenses/by/4.0/>/ [1, "http", 2:
>     "creativecommons.org", 6, "licenses", 6, "by", 6, "4.0", 6, ""]]
>   ]
>
> * FoaF example: Just for my understanding, would anything be wrong with
>   some application using <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
>   as the rel to foaf:Person here? (I figure that few RDF applications
>   treat rdf:type and iana:type as equivalent properties).
>
>   Later that's clarified a bit in A.1 where it says "same purpose", but
>   is rel:type in actual use anywhere? Otherwise, I suggest to go for
>   rdf:type right away, as that is in use. (It's more verbose when
>   expressed in non-CoRAL link formats, though.)
>
> * Only occurred to me when writing the above
>   extended-diagnostic-notation example: Might it make sense to allow
>   profile defined URIs as well, like common licenses or (when looking a
>   the FoaF example) types? They'd need to be told apart from numeric
>   literals that could just as well show up in a link target, but the iri
>   rule could get an additional `?(profiled: 9, uint)` entry that could
>   only exist on its own and expands like a numeric rel.
>
> * What to do with language-tagged attributes (like title*)? The takeaway
>   from links-json is that they can be decoded easily but need to keep
>   their language information. That's easily expressed in RDF (turtle:
>   `<> :title "Überschrift"@de`). links-json went for
>   `{"title":{"de":"Überschrift"}}`, which seems a bit crude to me but
>   could work just as well for CoRAL, as could a tagged CBOR array or a
>   plain array if we stared using arrays with discriminators that are not
>   part of the IRI discriminators as something different than IRIs (a la
>   `[/link/ 2, /attr:title/ 42, [/language-tagged/ -1, "de",
>   "Überschrift"]]`).
>
> * Appendix C: Do I understand correctly that there are some CBOR encoded
>   relative references that can not (even when knowing the rel in
>   append-relation) be expressed in a relative-ref? In particular, those
>   would be the append-* types. If so, it would be prudent to point out
>   right next to where it says that "CBOR-encoded IRI References are not
>   capable of expressing all IRI references".
>
> * Most of the URI resolution gets away without string comparisons. I'd
>   like to suggest making "../" an explicit URI option (say, a `*(parent:
>   5.5)` that'd go between path.type and and path. References with
>   dot-segments inside them are probably safe to put in the "not capable
>   of expressing all" category.
>
>   As I understand URI resolution, we don't need a "./" because that only
>   needs to be explicit when starting with something that has a colon in
>   it that's not the scheme's colon, otherwise "./x/y" is always
>   equivalent to "x/y".
>
> * Speaking of expressiveness of the encoded URIs: (Especially as urn: is
>   used in the document,) would it hurt to grow the encoded references
>   such that they can encode urns? It might be sufficient to allow scheme
>   without a host/port but a path.
>
>   Apropos port: Why must this be present after a host name? This
>   complicates round-tripping to URIs (because the algorithm has to know
>   to fill in default ports of all protocols), limits applicability to
>   portless protocols and adds some bytes -- and in the embedded
>   implementation, adding a default port can be as easy as just setting
>   it at initialization time before parsing.
>
> * Appendix C: A state transition diagram like the ones on
>   http://json.org/ could be as expressive as the list in C.3 while being
>   easier to grasp.
>
> * How are compressed URIs expressed in CBOR? Flat [6, "foo", 6, "bar"]
>   or nested [[6, "foo"], [6, "bar"]]? My first reading (and current
>   implementation) resulted in "nested", supported by the `(option,
>   value) = href[0]` line in C4, but reading C.1 with the CDDL spec next
>   to it (and running the cddl tool) rather indicates "flat" to me.
>
>   Either way, some examples would be great.
>
> * Nit: calling a sequence of options _absolute_ brings up the
>   association of the "absolute URI", which is not the same as "URI"
>   (which is by definition not a reference, but sometimes it helps to say
>   "full URI"). An Absolute URI would not have a fragment identifier (and
>   is defined to ease definign protocols where the fragment is never
>   sent), whereas the non-relative or full option sequence described here
>   can easily (and should be able to) contain a fragment identifier.
>
> * Is there a difference between a CoRAL registry and a CoRAL profile?
>   Both terms are used.
>
> Best regards
> Christian