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

Julian,

Thanks for the really detailed and helpful review!  

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.

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

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

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

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

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

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

What does the WG think?

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

Yes, already opened up a ticket on that:
http://trac.tools.ietf.org/wg/core/trac/ticket/192

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

Carsten touched on this, we'll look at a better way.

>   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/
> _______________________________________________
> core mailing list
> core@ietf.org
> https://www.ietf.org/mailman/listinfo/core

Thanks,
Zach

-- 
Zach Shelby, Chief Nerd, Sensinode Ltd.
http://www.sensinode.com
http://zachshelby.org  - My blog "On the Internet of Things"
http://6lowpan.net - My book "6LoWPAN: The Wireless Embedded Internet"
Mobile: +358 40 7796297