Subject: [core] Modernized Link Format

From: Klaus Hartke <[email-masked]>
Date: Thu, 11 Oct 2018 13:47:30 +0200

I've done a quick review of appendix D of the Resource Directory draft
[1]. If I understand correctly, the section obsoletes Section 2.1 of
RFC 6690 [2]...

   Each link conveys one target URI as a URI-reference inside angle
   brackets ("<>").  The context URI of a link (also called the base URI
   in [RFC3986]) is determined by the following rules in this
   specification:

   (a)  The context URI is set to the anchor parameter, when specified.

   (b)  Origin of the target URI, when specified.

   (c)  Origin of the link format resource's base URI.

...and replaces it with the following new rules:

   o  The URI-reference inside angle brackets ("<>") describes the
      target URI of the link.

   o  The context of the link is expressed by the "anchor" parameter.
      If the anchor attribute is absent, it defaults to the empty
      reference ("").

   o  Both these references are resolved according to Section 5 of
      [RFC3986].

The resolution of the anchor URI in the final step is presumably
performed against the URI used to retrieve the Link Format document.

This means that the link in the following Link Format document located
at <coap://example.com:1234/.well-known/core>...

    <foo/bar>

...would resolve to the following URI under the old rules...

    coap://example.com:1234/foo/bar

...and  to the following URI under the new rules...

    coap://example.com:1234/.well-known/foo/bar

...regardless of whether "rel" is the implicit "hosts" relation type
as in this example or any other relation type.

Is that correct?

While the impact of this change on existing deployments might be low,
it's a breaking change and as such IMO requires an RFC that updates or
obsoletes RFC 6609.

Klaus

[1] https://tools.ietf.org/html/draft-ietf-core-resource-directory-15#appendix-D
[2] https://tools.ietf.org/html/rfc6690#section-2.1

---

From: Christian Amsüss <[email-masked]>
Date: Thu, 11 Oct 2018 14:47:01 +0200

Hello Klaus,

thanks for comment.

On Thu, Oct 11, 2018 at 01:47:30PM +0200, Klaus Hartke wrote:
> ....would resolve to the following URI under the old rules...
> 
> ....and  to the following URI under the new rules...
> 
> ....regardless of whether "rel" is the implicit "hosts" relation type

Yes. (In neither document, an explicit or implicit rel has an impact on
the reference resolution.)

> it's a breaking change and as such IMO requires an RFC that updates or

The new interpretation is only used when an application explicitly
specifies it (as does the RD). Applications "in the wild" are, as it is
written now, not affected.

The choices we have in RD are, to my understanding, as follows:

a) What is in -15: Bend link-format only when used in RD (or any other
  document that opts in to that -- I figure core-interfaces will)

b) Update 6690...

  b1) ... in a 6690bis

  b2) ... in Resource Directory

c) Use 6690 interpretation in RD

We've ruled out c) over the last year b/c it means that features of the
RD will not be available (ie. some links can not be expressed in any
serialization format) until one can actually use a format that doesn't
suffer from 6690's weird resolution rules (ie. CoRAL or 6690bis).
Moreover, if we went by c, any deployed RD would keep us from a 6690bis,
for an RD implementation needs to resolve URIs.

Among b and a, a was picked because hopes were that would allow for the
fastest progress of RD which is way behind schedule; also, it allows
doing b1 later easily. I'm all for doing any of the b options, but I
don't rather not have them delay the RD.

What puts me off b1 a bit is that it'll attract fixes to other oddities
of 6690 too (eg. clarifying rel=hosts, recommending against
whitespace-separated values), delaying RD by a year or more. (And that's
not even thinking of the links-json process).

Say we wanted to go for b2, as you suggest. Is that possible at all,
procedurally? How thorough would an investigation into the current users
need to be to allow re-using the content format number and media type?
(I have asked around and not seen or heard of a single implementation of
RFC6690 that relies on the odd behaviors, but obviously didn't ask all
readers of 6690. It appears to me that not even the original authors
were fully aware of their rules, or all examples would start with `<x`
rather than with `</x` for brevity.)

Best regards
Christian

-- 
Ceterum censeo RFC6690 esse revidendam.
 -- me, in mails from April on that topic

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 11 Oct 2018 15:28:34 +0200

Christian Amsüss wrote:
> serialization format)

Just to clarify: You can always, write link targets as "URI" or
"path-absolute" [RFC3986], right? (That's not very efficient but not
not expressible.)

> don't rather not have them delay the RD.

It creates a situation we really should avoid: A representation
format, identified by the "application/link-format" media type, that
changes its semantics depending on the context in which it is used (RD
or legacy application).

Thinking about it a bit more, I only see two ways forward: Keep the
"application/link-format" media type and add a version indicator to
the representation format that prevents legacy applications from
applying the wrong semantics. Or use an entirely different media type
(e.g., "application/link-format+cbor" with fixed rules,
"application/coral+cbor").

Klaus

---

From: Christian Amsüss <[email-masked]>
Date: Thu, 11 Oct 2018 15:53:22 +0200

> "path-absolute" [RFC3986], right? (That's not very efficient but not

Yes, *provided* you can construct the URI the requester had in mind when
accessing your system (the client might not have sent your host name
along).

Later changes in the base address are not possible (precise: not
meaningful) when all links were fully expanded. The protocol-negotiation
mechanisms not fully usable with fully expressed URIs either, as I
understand them.

> applying the wrong semantics.

That avoids the formal mess, but creates a practical one. Code is out
there that produces documents in "link-format;version=any" (documents
that work with both 6690 and modernized). Moving everything over to
link-format;version=2 at ct=39 creates formal clarity and practical
non-interoperability for them.

If there is but one righteous citizen of 6690, let them have the code
point. My impression is there is none.

> Or use an entirely different media type

I've asked the authors of link-format+{json,cbor} to do right that in
[1], but the version that's about to be released contains no
clarification to that matter AFAIK.

CoRAL -- yes, that's why I asked about whether we can have a preview
release of CoRAL without the research-ish forms parts in it. If CoRAL
were a document heading towards WGLC, I'd be happy to recommend CoRAL
for RD use on all sides, and state that link-format can be used per
RFC6690 but is limited as outlined in an appendix, and power users
should use CoRAL or better.

Best regards
Christian

[1]: https://mailarchive.ietf.org/arch/msg/core/eNSR6jnP-gvZZ_zHkb097sFQyog

-- 
To use raw power is to make yourself infinitely vulnerable to greater powers.
  -- Bene Gesserit axiom

---

From: Klaus Hartke <[email-masked]>
Date: Fri, 12 Oct 2018 10:47:20 +0200

> non-interoperability for them.

I was more thinking of keeping the media type and content format ID
and changing the payload to opt-in to the new semantics.

For example, the link in this representation of
<coap://example.com:1234/.well-known/core>...

    <foo/bar>

...would resolve to <coap://example.com:1234/foo/bar>, and the link in
this representation...

   \v2, <foo/bar>

would resolve to <coap://example.com:1234/.well-known/foo/bar>.

> should use CoRAL or better.

Let's accelerate CoRAL then.

Klaus

---

From: Christian Amsüss <[email-masked]>
Date: Wed, 17 Oct 2018 18:04:04 +0200

> would resolve to <coap://example.com:1234/.well-known/foo/bar>.

I'm not a bug fan of such in-line version negotiation, and faintly
remember a sentiment from somewhere within the WG that exactly those
things should be covered by content types.

If that's fine with everybody, it'll be with me too, but I more see this
as an incentive to...

> Let's accelerate CoRAL then.

...do this.

The last state I know are our discussions from March, since which
representations (formerly fat links) have been re-introduced.

Has CoRAL received any reviews since then? Is it progressing towards
adoption by T2TRG?

Would we need to / should we, if the RD were to forego fixing RFC6690
and rely on CoRAL to express what can't be said with link-format, do in
terms of implementation limits and profiles? Should there be a dedicated
profile for "CoRAL used as link-format replacement", or would you expect
the default profile to work here? Are there yet examples of a
.well-known/core file expressed in CoRAL?

I'm all for the approach, but at what time frame can it be realized, and
which working groups will need to be involved at which stage to avoid
surprises at IESG review? (Eg. equating target attributes with literal
properties under http://TBD/ is something that could need feedback from
RFC8288's WG^Wauthors^H or other RDF-using WGs.)

Best regards
Christian

---

From: Klaus Hartke <[email-masked]>
Date: Sun, 21 Oct 2018 18:04:20 +0200

> Has CoRAL received any reviews since then? Is it progressing towards

Adoption is now on the agenda of the T2TRG summary meeting in Bangkok
[1]. The draft hasn't seen any significant reviews since March,
though.

> the default profile to work here?

While the default profile technically works, it's not as efficient as
it can get since it doesn't assign numeric identifiers, e.g., to the
"hosts" relation type and RFC 6690 link attributes. So there should be
a profile that does for "Link Format in CoRAL" what
draft-ietf-core-links-json-10#section-2.3 [2] does for "Link Format in
CBOR". I don't know if that has to be a profile that is dedicated to
this application or if it'd make sense, for example, to have a general
"CoRE Profile" that works also for /.well-known/core and other CoRE WG
specifications.

> Are there yet examples of a

Here's one example from RFC 6690 [3] expressed in CoRAL:

OLD:

</sensors>;ct=40;title="Sensor Index",
</sensors/temp>;rt="temperature-c";if="sensor",
</sensors/light>;rt="light-lux";if="sensor",
<http://www.example.com/sensors/t123>;anchor="/sensors/temp";rel="describedby",
</t>;anchor="/sensors/temp";rel="alternate"

NEW:

#using <http://www.iana.org/assignments/relation/>
#using lf = <http://TBD/>

hosts </sensors> {
    lf:ct "40"
}

hosts </sensors/temp> {
    lf:rt "temperature-c"
    lf:if "sensor"
    describedby <http://www.example.com/sensors/t123>
    alternate </t>
}

hosts </sensors/light> {
    lf:rt "light-lux"
    lf:if "sensor"
}

> I'm all for the approach, but at what time frame can it be realized, and

I think it'd make sense to have at least one or two interop events, so
it depends on how quickly the draft gets adopted, implementations
created, interoperability confirmed, reviews done.

While I think the draft is already in quite a good state, I would
probably rather lean towards getting it right than rushing it out.

> RFC8288's WG^Wauthors^H or other RDF-using WGs.)

RFC 8288 gives some license to deviate from the spec where it makes
sense in different link serialization formats. For example,  Atom
allows IANA-registered link relation types to be serialized as URIs
using the prefix "http://www.iana.org/assignments/relation/", which is
specific to Atom (and adopted by CoRAL) and not part of RFC 8288 [4].
So I don't think there's a hard dependency on feedback from the RFC
8288 authors. Review from the RFC 8288 authors and other working
groups would be welcome, of course.

One thing that could raise eyebrows is if the CoRE WG started to
assign numeric identifiers to all IANA-registered link relation types
[5]. I thought of doing that in draft-hartke-core-apps-07 [6], but am
now not so sure if that is the right path.

Does anything else come to your mind that could lead to surprises at
IESG review?

Klaus

[1] https://github.com/t2trg/2018-ietf103
[2] https://tools.ietf.org/html/draft-ietf-core-links-json-10#section-2.3
[3] https://tools.ietf.org/html/rfc6690#page-14
[4] https://tools.ietf.org/html/rfc8288#appendix-A.2
[5] https://www.iana.org/assignments/link-relations/link-relations.xhtml
[6] https://tools.ietf.org/html/draft-hartke-core-apps-07#section-6.2

---

From: Jim Schaad <[email-masked]>
Date: Sun, 21 Oct 2018 09:32:31 -0700

Would it be possible to get a link to CoRAL as I don't think I have ever seen it.

> -----Original Message-----
> From: core <[email-masked]> On Behalf Of Klaus Hartke
> Sent: Sunday, October 21, 2018 9:04 AM
> To: Christian M. Amsüss <[email-masked]>
> Cc: [email-masked] WG <[email-masked]>
> Subject: Re: [core] Modernized Link Format
> 
> Christian Amsüss wrote:
> [1]. The draft hasn't seen any significant reviews since March, though.
> 
> > and rely on CoRAL to express what can't be said with link-format, do
> > in terms of implementation limits and profiles? Should there be a
> > dedicated profile for "CoRAL used as link-format replacement", or
> > would you expect the default profile to work here?
> 
> While the default profile technically works, it's not as efficient as it can get
> since it doesn't assign numeric identifiers, e.g., to the "hosts" relation type
> and RFC 6690 link attributes. So there should be a profile that does for "Link
> Format in CoRAL" what
> draft-ietf-core-links-json-10#section-2.3 [2] does for "Link Format in CBOR".
> I don't know if that has to be a profile that is dedicated to this application or
> if it'd make sense, for example, to have a general "CoRE Profile" that works
> also for /.well-known/core and other CoRE WG specifications.
> 
> I think it'd make sense to have at least one or two interop events, so it
> depends on how quickly the draft gets adopted, implementations created,
> interoperability confirmed, reviews done.
> 
> While I think the draft is already in quite a good state, I would probably
> rather lean towards getting it right than rushing it out.
> 
> > properties under http://TBD/ is something that could need feedback
> > from RFC8288's WG^Wauthors^H or other RDF-using WGs.)
> 
> RFC 8288 gives some license to deviate from the spec where it makes sense
> in different link serialization formats. For example,  Atom allows IANA-
> registered link relation types to be serialized as URIs using the prefix
> "http://www.iana.org/assignments/relation/", which is specific to Atom (and
> adopted by CoRAL) and not part of RFC 8288 [4].
> 8288 authors. Review from the RFC 8288 authors and other working groups
> would be welcome, of course.
> 
> One thing that could raise eyebrows is if the CoRE WG started to assign
> numeric identifiers to all IANA-registered link relation types [5]. I thought of
> doing that in draft-hartke-core-apps-07 [6], but am now not so sure if that is
> the right path.
> 
> Does anything else come to your mind that could lead to surprises at IESG
> review?
> 
> Klaus
> 
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: Klaus Hartke <[email-masked]>
Date: Sun, 21 Oct 2018 19:29:23 +0200

> Would it be possible to get a link to CoRAL as I don't think I have ever seen it.

https://tools.ietf.org/html/draft-hartke-t2trg-coral-05

Klaus

---

From: Jim Schaad <[email-masked]>
Date: Fri, 26 Oct 2018 15:45:24 -0700

Klaus,

Thanks for this pointer, I have read through this and decided to try and figure out how I think things work based on the document.  For this purpose I just took two of the responses from the resource directory interop and tried to put them into CoRAL

Example #1
The big question that I have here is the fact that I am using the base directive multiple times  I believe that this is correct.

    <coaps://new.example.com:5684/temp>;rt="temperature";ct=0
    <coaps://new.example.com:5684/light>;rt="light-lux";ct=0
    <coaps://new.example.com:5684/t>;anchor="coaps://new.example.com:5684/sensors/temp";rel="alternate"
    <http://www.example.com/sensors/t123>;anchor="coaps://new.example.com:5684/sensors/temp";rel="describedby"
    <coap://[2001:db8:4::1]/light/left>;rt="light";ct=0
    <coap://[2001:db8:4::1]/light/middle>;rt="light";ct=0
    <coap://[2001:db8:4::1]/light/right>;rt="light";ct=0

************************************

#base <coaps://new.example.com:5684>
#using attr = <http://TBD/>
<temp> {
    attr:rt "temperature"
    attr:ct "0"
}
<light> {
    attr:rt "light-lux"
    attr:ct "0"
}
<t> {
    alternate <coaps://new.example.com:5684/sensors/temp"
    describedby <coaps://new.example.com:5684/sensors/temp>
}
#base <coap://[2001:db8:4::1]
<light/left> {
    attr:rt "light"
    attr:ct "0"
}
<light/middle> {
    attr:rt "light"
    attr:ct "0"
}
<light/right>  {
    attr:rt "light"
    attr:ct "0"
}

**********************************

This example is a bit more difficult for me to know if it is correct - The anchor would, possibly, be used to resolve the URI but I note that anchor is explicitly not allowed to be an attribute of the link so I think this is the correct behavior but I am not sure.

</sensors/temp>;ct=41;rt="temperature-c";if="sensor";anchor="coap://spurious.example.com:5683"
</sensors/light>;ct=41;rt="light-lux";if="sensor"

*********************************

#using attr = <http://TBD/>
<coap://spurious.example.com:5683/sensors/temp> {
    attr:rt "temperature-c"
    attr:if "sensor"
}
<sensors/light> {
    attr:rt "light-lux"
    attr:if "sensor"
}

One last item - The current CBOR encoding plays games with a couple of different attributes - specifically the content type where it uses either an integer or an array of integers as the value.  I am not sure if you can have an attribute occur multiple times or not.  (Maybe ditto with links?) 

Jim

> From: Klaus Hartke <[email-masked]>
> Sent: Sunday, October 21, 2018 10:29 AM
> To: Jim Schaad <[email-masked]>
> Cc: Christian M. Amsüss <[email-masked]>; [email-masked] WG
> <[email-masked]>