Subject: [core] Throughout review on Link Format draft

From: Linyi Tian <[email-masked]>
Date: Fri, 08 Apr 2011 16:21:02 +0800

I did throughout review of this draft and provides the following comments:

Convention: 

[S1-P2] refers to [Section 1 - Paragraph 2]

[c1] refers to [comment 1 ]

1. [S1-P2] [c1] Is "constrained web server" the correct term? Should we
remove "web"?

"In this document we refer to the discovery of resources hosted by a
constrained web server, their attributes and other resource relations as
CoRE Resource Discovery."

2. [S1-P3] [c2] Add "application/link-format as defined in section 7.4" at
the end of following sentence to improve the readability. 

  The CoRE Link Format is carried as a payload and is assigned an Internet
media type.

3. [S1.1-P1] [S2.2-P2]

[c3] If the resource is not hosted by the server, how to indicate this info?
Since the "hosts" is the default relation type, should we define "external"
instead? 

The relation types in Link Format are used to describe the resources in
sensors. It is quite different with the web environment. I reviewed the
RFC5988 carefully and believe that most of the relation types can't be used
by Link Format. I suggest we have a table to list the ones that may be
applicable to link format.

4. [S1.3] [c4] typo in "Link" term. Change "a tarfet" to "a target". 

5. [S2-P3] [c5] typo in last sentence. Add "is" after "why it.useful".
Change "Unicode" to "Unicode"

See section 3 of [RFC5198], which explains why it useful to represent
Unicode in a single unique form. 

6. [S2.1] [c6] Examples should be added to improve the readability. I also
propose to use "Base URIs" to replace "Context URI" and rephrase the text as
following:

Section 2.1  Target and Base URIs

Each link conveys one target URI as a URI-reference inside angle brackets
("<>").  The base URI (defined 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 scheme and authority, the base URI is built from the
scheme and authority parts of the target resource which returning the set of
links. 

The CoRE link format includes one or more links, each describing a resource
hosted by a server using relation type "hosts". Other relations can be
expressed by including an anchor parameter (which defines the base 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 base
URI).  Thus the HTTP Link Header is by default relating the target URI to
the URI that was requested. See Section 5 of [RFC3986] for a description of
how URIs are constructed from URI references.

This example shows the base URI construction. ( I didn't update the example
since I believe something wrong inside).

REQ: GET /.well-known/core

   RES: 200 OK

   </sensors>;ct=40;rt="index";rt="Sensor Index",   -------base URI is xxxx

   </sensors/temp>;rt="TemperatureC";if="sensor",  ----base URI is xxxx

   </sensors/light>;ct=41;rt="LightLux";if="sensor", ---base URI is xxxx

   <http://www.example.com/sensors/t123>;anchor="/sensors/temp"

   ;rel="describedby",   ---base URI is xxxx

   </t>;anchor="/sensors/temp";rel="alternate" ---base URI is xxxx

7. [S3.1-P2] [c7] typo. Add "be" after "The resource type attribute is not
meant to ...used".

8. [S4-P2] [c8]What is the default port?

9. [S4.1-P2] [c9] Typo in the following sentence. What does "They name"
mean?

Other resource-param values refer to the link attribute they name

10.[S1.2.3-P2] [c10] resource directory service needs to be defined. How to
register the link format and how to access it per sensor basis need to be
defined.

11.[S2.2-P2][S5] [c11] I believe most of the relation types are not
appropriate for CoAP. For example, "alternate" is used together with "type",
"media" or other attributes for special meaning. You can refer to 4.12.4.1
of
http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#rel-a
lternate for further details. While in the example of section 5 of Link
Format, we use "alternate" to indicate the short URI which is not defined.
The same issue is for "described" in the example. It is used for reference
of POWER document while we use it for URI description. We'd better to have a
table to list the relation types that are applicable to CoAP rather than
saying that anyone can be used in section 2.2.