Subject: [T2TRG] Review of CIRIs (was: Review of CoRAL)

From: Klaus Hartke <[email-masked]>
Date: Tue, 22 Jan 2019 15:53:59 +0100

Hi Christian,

thanks again for your review. Here's the next batch of replies, this
time related to CIRIs.

Christian Amsüss wrote:
> * 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".

In principle, it is always to possible to use IRIs everywhere.
Relative references are more like a compression mechanism that allows
us to write IRIs more efficiently when they share a common base. In
that sense, there are no CIRI references that cannot be expressed by
an IRI reference:

    ciri_ref_to_iri_ref(ciri, base_ciri) = make_iri_relative(
                    ciri_to_iri(resolve_ciri(ciri, base_ciri)),
                    ciri_to_iri(base_ciri))

> * 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.

Good idea. My proposal would be to use the path.type option for this:

   path.type
      Specifies the type of the URI path for reference resolution.  The
      option value is an integer in the range 0 to 127, named as
      follows:

         0 - absolute-path
         1 - append-relation
         2 - append-path
         3 - relative-path
         4 - relative-path-1up
         5 - relative-path-2up
         6 - relative-path-3up
         7 - relative-path-4up
         ...

   path
      Specifies one segment of the URI path.  The option value can be
      any Unicode string with the exception of the strings "." and "..".
      This option can occur more than once.

>   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".

Good point. Removed with the above proposal.

> * 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.

Makes sense. It would be good to know that set of URIs we want to
support exactly and what the scheme-specific normalization rules are
for these (see also the discussion on comparisons in [1]).

>   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.

Ari also brought this up in his review. See the discussion in [1].

> * 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.

Added in -00.

> * 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.

Flat [6, "foo", 6, "bar"]. I'm adding a clarification and some
examples in the next draft revision.

>   Either way, some examples would be great.

Agreed. Working on it.

> * 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.

I see the potential confusion, but I don't have a good idea how to
phrase it in a better way. Any suggestions?

Klaus

[1] https://mailarchive.ietf.org/arch/msg/t2trg/7RIEEHql5Jm70TAzlOuQeXAwNfc

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 31 Jan 2019 17:56:29 +0100

Hi Christian,

here's the final batch of replies to the original review. (I hope
nothing got lost.)

Christian Amsüss <[email-masked]> wrote:
> * "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).

Hmm... it's not really a superset of RDF, since RDF has features like
the ability to describe arbitrary graphs of connected resources, blank
nodes, etc. that CoRAL doesn't. Strictly speaking, it's also not a
superset of Web Linking, since Web Linking has features like target
attributes that CoRAL doesn't.

I think the important thing here is to put the reader of the document
into the right mindset: It's all about navigating between REST
resources, constructing request messages, etc. and not so much about
reasoning in a knowledge graph.

> * 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?

I'd say the necessary history length depends entirely on the
application context. A history length of 1 or even 0 is probably
entirely sufficient in most cases. I'm de-emphasizing the session
history a bit in the next draft revision.

> * 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.

Forms are certainly something where some real-world examples would be
very useful. The high-level idea is:

- With links it's easy to find out what resources are available at a
device at a granular level (as opposed to just knowing that the device
has certain resources available based on device type).

- With forms it becomes easy to find out what operations are available
on these resources at a granular level (as opposed to just knowing
that the resource has certain operations available based on resource
type).

- With form data, it becomes easy to find out what parameters are
available on these operations at a granular level (as opposed to just
knowing that the operation has certain parameters available based on
operation type).

Of course, not every application will have a need for going into this
granular level of detail. But the idea is to provide this ability to
applications where a more granular evolution strategy is beneficial.

> * 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.

Populating cache with representations is tricky, since a cache in CoAP
(and HTTP) stores responses, not representations. I see embedded
representations mostly on the same level as the hints provided by most
link target attributes -- as hints. But I'm open to discussing more
narrow interpretations.

> * 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.

I'm restructuring things a bit in the next draft revision.

> * 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).

IMHO it's quite valuable to have a way for giving CoRAL examples with
precise semantics that don't drown in the syntactic overhead that
comes with expressing equivalent information in RDF (or some
XML/JSON/Link Format dialect). Examples are written by humans, who
also might want to store or transport them without losing the semantic
information of grouping, indentation, or comments.

I agree with some of the concerns related to intuition when coming
from Turtle or going to the binary format. If there are ideas how the
textual format could be improved, I'm very interested to include them.

> * 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.

Yes. My proposal would be to set up a dictionary of key-value entries,
with keys being unsigned integers and values being either an IRI, an
integer, a string, etc. These dictionary entries could be referenced
both at places where link relation types occur and where link targets
occur. I'm adding a proposal to the next draft revision.

Klaus

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 31 Jan 2019 18:03:20 +0100

On Jan 31, 2019, at 17:56, Klaus Hartke <[email-masked]> wrote:
> 
> dictionary of key-value entries,
> integer, a string, etc.

This could be part of the format, or it could be a separate compression on top.

I looked at this in the context of W3C TD:
https://www.w3.org/2017/07/wot-f2f/slides/w3c-serialization.pdf

Grüße, Carsten