Re: [apps-discuss] [core] APPSDIR review of draft-ietf-core-link-format-11

[Julian Reschke <[e-mail]>]

On 2012-03-09 12:35, Zach Shelby wrote:
> Julian,
>
> Thanks for the really detailed and helpful review!

Well, sometimes a review request comes in where I actually can 
contribute (hopefully) :-)

> On Feb 28, 2012, at 9:49 PM, Julian Reschke wrote:
>>
>> Major Issues:
>>
>> 2.2.  Link relations
>>
>>    Since links in the CoRE Link Format are typically used to describe
>>    resources hosted by a server, and thus in the absence of the relation
>>    parameter the new relation type "hosts" is assumed (see Section 7.2).
>>
>> It took me a moment to realize that "hosts" isn't the plural of "host" here. Maybe a different relation name would make things clearer (although I currently have no better proposal :-).
>
> Boy was that a fun discussion on the WG list as well, and hosts is what we ended up with... Maybe just adding some explanatory text right there would help.

+1

>>    The "hosts" relation type indicates that the target URI is a resource
>>    hosted by the server given by the base URI, or, if present, the
>>    anchor parameter.
>>
>> So the rule for determining the context URI is different for this link relation? I believe this needs to change.
>
> Originally it was for the whole link format, and I think with the rules you suggest below we can make it generic again.

Sounds good.

>>    To express other relations, links can make use of any registered
>>    relation by including the relation parameter.  To simplify the
>>    constrained implementations, the value of a "rel" parameter in this
>>    link format SHOULD NOT contain more than one relation type.  There
>>
>> That's a SHOULD NOT that doesn't help anybody. Are recipients supposed to understand multiple relation types or not? If yes, then the constraint isn't needed. If no, it's a MUST NOT.
>
> The only reason we left the door open for allowing multiple relation types, was in case other Web Links were converted to this format (and thus may have multiple relation types). Constrained devices are not expected to understand multiple relation types. I would recommend that we just remove the SHOULD NOT.

Well, you could serialized multiple relations in one link instance into 
multiple links.

>>    may be cases where multiple relation types cannot be avoided, for
>>    example when storing a RFC5988 Link header in this link format.  The
>>    context of a relation can be defined using the anchor parameter.  In
>>    this way, relations between resources hosted on a server, or between
>>    hosted resources and external resources can be expressed.
>>
>> This seems to repeat information from earlier on...
>>
>>
>> 3.  CoRE link extensions
>>
>>    The following CoRE specific target attributes are defined in addition
>>    to the ABNF rules in Section 5 of [RFC5988].  These attributes
>>    describe information useful in accessing the target link of the
>>    relation, and in some cases may be URIs.  These URIs MUST be treated
>>
>> s/may be/can use the syntactical form of a/
>>
>>    as non resolvable identifiers (they are not meant to be retrieved).
>>
>> Not sure about the "MUST". Maybe replace with an explanation that they can indeed by dereferenced (for instance to obtain a description of the link relation), but that this is not part of the protocol and MUST NOT be done automatically on link evaluation.
>
> Good suggestion, I will make a ticket. We do need to check that this is consistent with RFC5988, as my understanding of target attributes was that they are not meant to be retrieved (checking again though, I can't find text in RFC5988 that contradicts what you are suggesting).

Consistency with 5988 is good :-) The main point here is that processing 
the link doesn't *need* dereferencing the link; but there may be other 
cases, such as looking up information, when it's useful to do so.

>>    When attributes are compared, they MUST be compared as strings.
>>
>> Attribute values?
>>
>>    Relationships to resources that are meant to be retrieved should be
>>    expressed as separate links using the anchor attribute and the
>>    appropriate relation type.
>>
>> It's not clear to me what this means. Could you elaborate?
>
> Basically a work-around for the MUST you suggested replacing above. This text would be removed if that change is made.
>
>>       link-extension    =<Defined in RFC5988>
>>       link-extension    =/ ( "rt=" quoted-string )
>>       link-extension    =/ ( "if=" quoted-string )
>>       link-extension    =/ ( "sz=" cardinal )
>>       cardinal          = "0" / %x31-39 *DIGIT
>>
>> In here, you copied the ABNF style from RFC 5988. I think that style is something we should avoid, though, because it encourages parsers to special case certain attributes.
>>
>> I would recommend to allow both token and quoted-string for all new parameters.
>>
>> (and yes, I'll raise an erratum against RFC 5988 once we have done the base work in HTTPbis)
>
> Carsten already touched on this, and I will make a ticket.
>
>>
>> 3.1.  Resource type 'rt' attribute
>>
>>    The resource type "rt" attribute is an opaque string used to assign a
>>    semantically important type to a resource.  One can think of this as
>>    a noun describing the resource.  In the case of a temperature
>>    resource this could be e.g. an application-specific semantic type
>>    like "OutdoorTemperature", a Universal Resource Name (URN) like
>>    "urn:temperature:outdoor" or a URI referencing a specific concept in
>>    an ontology like
>>
>>    "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature".  Multiple
>>    resource type attributes MAY appear in a link.
>>
>> Please avoid that. In general, the format that you're borrowing from doesn't allow multiple parameters with the same name. Either make it multiple links, or allow a white-space separated list of values in the attribute value.
>
> Right, same goes for if=. In theory we could allow multiple values separated by a white-space, like in the rel= attribute. This makes the attribute matching more difficult however. At the same time including multiple links is wasteful overhead. So far when applying these in designs only a single rt= or if= attribute has been needed, but I could foresee multiple values in the future.

If you require the separator to be a single SP, matching can be done by 
doing

   contains(concat(" ",value," "),concat(" ",searchfor," ")

so it's no too hard.

>>    The resource type attribute is not meant to used to assign a human
>>    readable name to a resource.  The "title" attribute defined in
>>    [RFC5988] is meant for that purpose.
>>
>> Did you consider using the type attribute that already is defined in RFC 5988?
>
> type= refers to the Media Type, and this is already used also in this format for that purpose.
>
>> 5.  Examples
>>
>>    A few examples of typical link descriptions in this format follows.
>>    Multiple resource descriptions in a representation are separated by
>>    commas.  Linefeeds never occur in the actual format, but are shown in
>>    these examples for readability.  Although the following examples use
>>    CoAP response codes, the examples are applicable to HTTP as well (the
>>    corresponding response code would be 200 OK).
>>
>> Actually, RFC 5988 allows CR LF between parameters as it uses the RFC 2616 list production allowing implied LWS.
>>
>> If you want to rule this out, you probably need to specify your own ABNF.
>
> I would not mind allowing the CR LF actually, but do we really inherit that from the RFC 2616 production as we are not inside the HTTP header anymore?

It's part of the ABNF, not something specific to header fields. So yes, 
it does inherit that.

>>    This example arranges link descriptions hierarchically, with the
>>    entry point including a link to a sub-resource containing links about
>>    the sensors.
>>
>>    REQ: GET /.well-known/core
>>
>>    RES: 2.05 "Content"
>>    </sensors>;rt="index"
>>
>>    REQ: GET /sensors
>>
>>    RES: 2.05 "Content"
>>    </sensors/temp>;rt="TemperatureC";if="sensor",
>>    </sensors/light>;rt="LightLux";if="sensor"
>>
>> rt="index" is mentioned for the first time here. Is this something recipients need to understand, so is it predefined? Also, isn't this a use case for rel=index?
>
> Yep, "index" is not a great example here. I will update this to be more appropriate.
>
>> Minor Issues:
>>
>>    The main function of such a discovery mechanism is to provide
>>    Universal Resource Identifiers (URIs, called links) for the resources
>>
>> Nope. As discussed further down below, a link requires two resources, not a single one.
>>
>> 2.1.  Target and context URIs
>>
>>    Each link conveys one target URI as a URI-reference inside angle
>>    brackets ("<>").  The context URI of a link (also called base URI in
>>    [RFC3986]) conveyed in the CoRE Link Format is by default built from
>>    the scheme and authority parts of the target URI.  In the absence of
>>
>> OK, so
>>
>>   <http://example.com/foo>; rel=bar
>>
>> represents the link
>>
>>   http://example.com --bar-->  http://example.com/foo
>>
>> ? Sounds a bit counter-intuitive to me; maybe you should explain that in examples.
>
> It is intuitive for our main use case, which is describing the resources hosted by that server using the rel=hosts relation. But yes, I can add more example.
>
>>
>>    this information in the target URI, the context URI is built from the
>>    scheme and authority that was used for referencing the resource
>>    returning the set of links, replacing the path with an empty path.
>>
>>    Thus by default links can be thought of as describing a target
>>    resource hosted by the server.  Other relations can be expressed by
>>    including an anchor parameter (which defines the context URI) along
>>    with an explicit relation parameter.  This is an important difference
>>    to the way the HTTP Link Header format is used, as it is included in
>>    the header of an HTTP response for some URI (this URI is by default
>>    the context URI).  Thus the HTTP Link Header is by default relating
>>    the target URI to the URI that was requested.  In comparison, the
>>    CoRE link format includes one or more links, each describing a
>>    resource hosted by a server by default.  Other relations can be
>>    expressed by using the anchor parameter.  See Section 5 of [RFC3986]
>>    for a description of how URIs are constructed from URI references.
>>
>> Alternative explanation:
>>
>> The context URI specified by
>>
>> a) the anchor parameter, when specified, or
>>
>> b) protocol + authority of the target URI, when specified
>>
>> c) protocol + authority of the link format document's base URI.
>>
>> It would be nice if the reason why only protocol + authority are used.
>
> I like this way of explaining it, will make a ticket.
>
>> (you may also want to use the term "Origin" (RFC 6454) for protocol + authority)
>
> Richard Barnes also suggested this in his review, added a ticket already:
> http://trac.tools.ietf.org/wg/core/trac/ticket/191
>
>> 2.3.  Use of anchors
>>
>>    As per Section 5.2 of [RFC5988] a link description MAY include an
>>    "anchor" attribute, in which case the context is the URI included in
>>    that attribute.  This is used to describe a relationship between two
>>    resources.  A consuming implementation can however choose to ignore
>>    such links.  It is not expected that all implementations will be able
>>    to derive useful information from explicitly anchored links.
>>
>> Right. Maybe make clear that recipients MUST either process anchor correctly, or ignore the whole link relation (not only the anchor parameter).
>
> OK.
>
>> 7.2.  New 'hosts' relation type
>>
>>    This memo registers the new "hosts" Web Linking relation type as per
>>    [RFC5988].
>>
>>    Relation Name: hosts
>>
>>    Description: Refers to a resource hosted by the server indicated by
>>    the link context.
>>
>> Does that indicate more than "is one the same server"? In which case I believe no link relation is needed.
>
> We are using this to indicate:
>
> Origin ->  hosts ->  Target URI
>
> e.g.
>
> coap://this.server ->  hosts ->  /sensor/temperature (and has these attributes)
>
> How would we relate this following Web Linking without a relation?

By specifying an untyped link...

 > ...

Best regards, Julian