Subject: [core] draft-ietf-core-link-format-00 comments

From: Peter Bigot <[email-masked]>
Date: Thu, 21 Oct 2010 14:12:33 -0500

Section 2:

   CoRE resource discovery extends the HTTP Link Header format specified
   in [I-D.nottingham-http-link-header
<http://tools.ietf.org/html/draft-ietf-core-link-format-00#ref-I-D.nottingham-http-link-header>]
which is specified in Augmented
   Backus-Naur Form (ABNF) notation [RFC5234
<http://tools.ietf.org/html/rfc5234>].  The format does not

I-D.nottingham-http-link-header (RFC-to-be 5988) uses the ABNF notation of
RFC2616, not RFC5234.  RFC2616 defines its own syntax, and is not compatible
with that of RFC5234 or its predecessor RFC2234, which is what is used by
RFC3986 to define URI syntax.  This draft is indeed using the 2616, not
5234, syntax: witness the use of vertical bar instead of forward slash for
alternatives.

   The CoRE link format uses the ABNF description and associated rules
   in Section 5 of [I-D.nottingham-http-link-header
<http://tools.ietf.org/html/draft-ietf-core-link-format-00#ref-I-D.nottingham-http-link-header>].
 The "Link:" text

It's probably worth noting, as I-D.nottingham-http-link-header does, that
the rules for URI, URI-reference (misspelled URI-Reference in nottingham),
and pchar (see far below) are taken from RFC3986.

      link-extension    = ( "d" "=" <"> URI <">)
      link-extension    = ( "sh" "=" <"> URI-Reference <">)
      link-extension    = ( "n" "=" ( quoted-string | URI ) )
      link-extension    = ( "ct" "=" integer )
      link-extension    = ( "id" "=" ( quoted-string | URI ) )
      integer           = 1*DIGIT

The reference to "URI" in "d" should probably be a URI-reference.

The reference to "URI-Reference" in "sh" should be a URI-reference.

The addition of URI as an alternative to quoted-string for "n" and "id"
results in syntactic ambiguities.  Like the other URI instances, these would
have to be enclosed in quotes, and therefore could not be distinguished from
quoted-string values.  The reference to URI in these rules should be
removed, or an alternative quoting character found to distinguish them from
quoted-string.  (Although a URI value for "n" makes sense, "id" is already
described as an opaque string with examples of a UUID or XRI; I suggest just
dropping URI from the syntax rules, and mentioning it in the descriptive
text if necessary.)

Section 2.1

2.1.  Target and context IRIs

The term IRI is undefined in this document.  As CoAP doesn't deal with
internationalization, make this URI?

   Each link description conveys one target URI as a URI-Reference
   inside angle brackets ("<>").  The context of a link conveyed in the
   description is by default the URI of the resource that returned the
   link-format representation (usually ./well-known/core).  Thus each

Although I-D.nottingham-http-link-header does refer to a "context IRI", the
term "base URI" is used in RFC3986, and may be more familiar to readers.  A
reference to section 5 of RFC3986 may be helpful to remind readers how URIs
are constructed from URI references.

"./well-known/core" is a URI reference, not a URI, and can't serve as the
base: it lacks the scheme and authority parts of the URI.  I suggest simply
removing the parenthetical remark.

   implementation can however choose to ignore such links.  It is not
   expected that most implementations will be able to derive useful from
   explicitly anchored links.

Insert "information" between "useful from"?

Section 2.5

   The resource name "n" attribute is used to assign eith a human
   readable or a semantically important name to a resource.  In the case

s/eith/either/

Section 3:

   descriptions) offered by that constrained server.  Well-known
   resources have a reserved base URI "/.well-known/" as specified in
   [RFC5785 <http://tools.ietf.org/html/rfc5785>].  This document
defines a new well-known URI for CoRE
   discovery "/.well-known/core" Section 5.1
<http://tools.ietf.org/html/draft-ietf-core-link-format-00#section-5.1>.
 A server implementing
   this specification MUST support this URI on the default port
   appropriate for the protocol for the purpose of resource discovery.

"./well-known/" is not a base URI.  The term used in RFC5785 is "path
prefix".  This should be rewritten as:

... Well-known resources have a path component that begins with
"/.well-known/" as specified in  [RFC5785]. This document defines a new
well-known path prefix for CoRE discovery "/.well-known/core"  [Section
5.1].  A server implementing this specification MUST support this path
prefix on the default port....

Section 3.1:

   A server implementing this document MAY support the query string
   /.well-known/core? with uri= corresponding to the link-value or any
   of the resource description attributes for the purpose of filtering a

Rephrase?  /.well-known/core? is not a query string, and in fact the syntax
for the query part of a URI does not insist on key=value elements.  If this
is to be included, full syntax for a query part of the URI within the
well-known path should be included.

   (if any).  Implementations supporting filtering MUST also support
   wildcard * endings.  If resource descriptions are organized

This assumes somebody knows what supporting wildcard * endings means.  I
could guess.

In the spirit of being helpful, perhaps:

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:

  filter-query = resource-param "=" query-pattern
  resource-param = "uri" | "d" | "sh" | "n" | "id"
  query-pattern = 1*pchar [ "*" ]

The resource-param "uri" refers to the URI-reference between the "<" and ">"
characters of a link-value.  Other resource-param values refer to the link
attribute they name.  (TBD: Do we want to add the resource description
attributes that I excluded, or the standard link-param attributes from
I-D.nottingham-http-link-header?)  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.

If the decoded query-pattern does not end with "*", a link value matches the
query only if the value of the attribute or URI-reference denoted by the
resource-param is bytewise identical to the query-pattern.  If the decoded
query-pattern ends with "*", it is sufficient that the remainder of the
query-pattern be a prefix of the value denoted by the resource-param.

Not that I'm happy with this, but maybe it's a start?

(The legal characters for a query part of a URI are defined by RFC3986,
which does not use the same ABNF syntax as this document.  quoted-string
includes characters that cannot be part of a query, so I had to go with
1*pchar.  Understand that doing this introduces the concept of pct-encoded
characters, such as %22 to denote a double quote, or %20 for space.  Since
we will probably carry the Uri-Query option in its unencoded form, this may
not matter.  As usual, everything gets messy when you try to be formal and
start seeing the border cases.)

---

From: Zach Shelby <[email-masked]>
Date: Fri, 22 Oct 2010 13:24:13 +0300

Peter,

Thanks for the feedback on link-format. I will work on these improvements in the next version, not sure if I can do that for the Oct 25th cutoff. If not then I'll update the draft when submission opens up again in Beijing.

Zach

On Oct 21, 2010, at 10:12 PM, Peter Bigot wrote:

> ] which is specified in Augmented
> ].  The format does not
> I-D.nottingham-http-link-header (RFC-to-be 5988) uses the ABNF notation of RFC2616, not RFC5234.  RFC2616 defines its own syntax, and is not compatible with that of RFC5234 or its predecessor RFC2234, which is what is used by RFC3986 to define URI syntax.  This draft is indeed using the 2616, not 5234, syntax: witness the use of vertical bar instead of forward slash for alternatives.
> ].  The "Link:" text
> It's probably worth noting, as I-D.nottingham-http-link-header does, that the rules for URI, URI-reference (misspelled URI-Reference in nottingham), and pchar (see far below) are taken from RFC3986.
> The addition of URI as an alternative to quoted-string for "n" and "id" results in syntactic ambiguities.  Like the other URI instances, these would have to be enclosed in quotes, and therefore could not be distinguished from quoted-string values.  The reference to URI in these rules should be removed, or an alternative quoting character found to distinguish them from quoted-string.  (Although a URI value for "n" makes sense, "id" is already described as an opaque string with examples of a UUID or XRI; I suggest just dropping URI from the syntax rules, and mentioning it in the descriptive text if necessary.)
> 
> Section 2.1
> The term IRI is undefined in this document.  As CoAP doesn't deal with internationalization, make this URI?
> Although I-D.nottingham-http-link-header does refer to a "context IRI", the term "base URI" is used in RFC3986, and may be more familiar to readers.  A reference to section 5 of RFC3986 may be helpful to remind readers how URIs are constructed from URI references.
> 
> "./well-known/core" is a URI reference, not a URI, and can't serve as the base: it lacks the scheme and authority parts of the URI.  I suggest simply removing the parenthetical remark.
>    [
> RFC5785].  This document defines a new well-known URI for CoRE
>    discovery "/.well-known/core" Section 5.1.  A server implementing
> 
> "./well-known/" is not a base URI.  The term used in RFC5785 is "path prefix".  This should be rewritten as:
> 
> ... Well-known resources have a path component that begins with "/.well-known/" as specified in  [RFC5785]. This document defines a new well-known path prefix for CoRE discovery "/.well-known/core"  [Section 5.1].  A server implementing this specification MUST support this path prefix on the default port....
> 
> Section 3.1:
> Rephrase?  /.well-known/core? is not a query string, and in fact the syntax for the query part of a URI does not insist on key=value elements.  If this is to be included, full syntax for a query part of the URI within the well-known path should be included.
> This assumes somebody knows what supporting wildcard * endings means.  I could guess.
> 
> 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:
> 
> The resource-param "uri" refers to the URI-reference between the "<" and ">" characters of a link-value.  Other resource-param values refer to the link attribute they name.  (TBD: Do we want to add the resource description attributes that I excluded, or the standard link-param attributes from I-D.nottingham-http-link-header?)  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.
> 
> If the decoded query-pattern does not end with "*", a link value matches the query only if the value of the attribute or URI-reference denoted by the resource-param is bytewise identical to the query-pattern.  If the decoded query-pattern ends with "*", it is sufficient that the remainder of the query-pattern be a prefix of the value denoted by the resource-param.
> 
> (The legal characters for a query part of a URI are defined by RFC3986, which does not use the same ABNF syntax as this document.  quoted-string includes characters that cannot be part of a query, so I had to go with 1*pchar.  Understand that doing this introduces the concept of pct-encoded characters, such as %22 to denote a double quote, or %20 for space.  Since we will probably carry the Uri-Query option in its unencoded form, this may not matter.  As usual, everything gets messy when you try to be formal and start seeing the border cases.)
> 
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

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