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

[Julian Reschke <[e-mail]>]

I have been selected as the Applications Area Directorate reviewer for 
this draft (for background on appsdir, please see 
http://trac.tools.ietf.org/area/app/trac/wiki/ApplicationsAreaDirectorate)

Please resolve these comments along with any other Last Call comments 
you may receive. Please wait for direction from your document shepherd 
or AD before posting a new version of the draft.

Document: draft-ietf-core-link-format-11
Title: CoRE Link Format
Reviewer: Julian Reschke
Review Date: 2012-02-28
IETF Last Call Date: 2012-02-14
IESG Telechat Date: ?

Summary: This draft is almost ready for publication as an Standards 
Track RFC but has a few issues that should be fixed before publication

(I tried to categorize into Major/Minor/Nits but sometimes left Nits in 
context so that they appear under Major/Minor)

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

    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.

    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.

    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.

    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?

       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)

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.

    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?


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.

    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?




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.

    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.

(you may also want to use the term "Origin" (RFC 6454) for protocol + 
authority)


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


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.


Nits:

Abstract

    This document defines Web Linking using a link format for use by
    constrained web servers to describe hosted resources, their
    attributes and other relationships between links.  Based on the HTTP
    Link Header format defined in RFC5988, the CoRE Link Format is

Please s/header/header field/ throughout.

    Resource Discovery can be performed either unicast or multicast.
    When a server's IP address is already known, either a priori or
    resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast
    discovery is performed in order to locate the entry point to the
    resource of interest.  This is performed using a GET to /.well-known/
    core on the server, which returns a payload in the CoRE Link Format.
    A client would then match the appropriate Resource Type, Interface
    Description and possible Content-Type [RFC2045] for its application.

"Media type, as specified in the type attribute"?

    CoRE Link Format
       A particular serialization of typed links based the HTTP Link
       Header serialization defined in Section 5 of RFC5988, but carried
       as a resource representation with a MIME type.

s/MIME type/Internet Media Type/

    Attribute
       Properly called "Target Attribute" in RFC5988.  A set of key/value
       pairs that describe the link or its target.

One attribute is a *single* key/value pair...


3.2.  Interface description 'if' attribute

    The Interface Description "if" attribute is an opaque string used to
    provide a name, URI or URN indicating a specific interface definition

URNs are a subset of URIs...

    used to interact with the target resource.  One can think of this as
    describing verbs usable on a resource.  The Interface Description
    attribute is meant to describe the generic REST interface to interact
    with a resource or a set of resources.  It is expected that an
    Interface Description will be re-used by different resource types.
    For example the resource types "OutdoorTemperature", "DewPoint" and
    "RelHumidity" could all be accessible using the Interface Description
    "http://www.example.org/myapp.wadl#sensor".

    The Interface Description could be for example the URI of a Web
    Application Description Language (WADL) [WADL] definition of the
    target resource "http://www.example.org/myapp.wadl#sensor", a URN
    indicating the type of interface to the resource "urn:myapp:sensor",
    or an application-specific name "Sensor".  Multiple Interface
    Description attributes MAY appear in a link.

(see above)

3.3.  Maximum size estimate 'sz' attribute

    The maximum size estimate attribute "sz" gives an indication of the
    maximum size of the resource indicated by the target URI.  This

Checking: is "size of the resource" sufficiently defined in Core? In 
HTTP it would need a somewhat more complex definition ("payload returned 
upon GET...").

4.1.  Query Filtering

    A server implementing this document MAY recognize the query part of a
    resource discovery URI as a filter on the resources to be returned.
    The query part should conform to the following syntax (parmname is as
    defined in [RFC5988], pct-encoded and unreserved are defined in
    [RFC3986]).  Note that this only defines querying for a single
    parameter at a time.

I note that hardwiring URI query parameters into the protocol is *not* 
Restful.

Also, you probably need to state how to present non-ASCII parameter 
characters in the parameter (UTF8-encode-then-percent-escape...)

           filter-query = resource-param "=" query-pattern
           resource-param = "uri" / parmname
           query-pattern = search-token [ "*" ]
           search-token = *search-char
           search-char = unreserved / pct-encoded
                       / ":" / "@"   ; from pchar
                       / "/" / "?"   ; from query
                       / "!" / "$" / "'" / "(" / ")"
                       / "+" / "," / ";" / "="  ; from sub-delims

    The resource-param "uri" refers to the URI-reference between the "<"
    and ">" characters of a link.  Other resource-param values refer to
    the link attribute they name.  Filtering is performed by comparing
    the query-pattern against the value of the attribute identified by
    the resource-param for each link-value in the collection of resources
    identified by the URI path.

Which makes it impossible to use "uri" as link attribute. Maybe this 
should be noted. Alternatively maybe use a format that doesn't require 
overloading the name.


    This example shows the use of an anchor attribute to relate the
    temperature sensor resource to an external description and to an
    alternative URL.

s/URL/URI/