Subject: [core] I-D Action: draft-ietf-core-link-format-13.txt

From: [email-masked]
Date: Wed, 23 May 2012 12:57:59 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories. This draft is a work item of the Constrained RESTful Environments Working Group of the IETF.

	Title           : CoRE Link Format
	Author(s)       : Zach Shelby
	Filename        : draft-ietf-core-link-format-13.txt
	Pages           : 25
	Date            : 2012-05-23

   This specification 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 field defined in RFC5988, the CoRE Link Format is carried
   as a payload and is assigned an Internet media type.  A well-known
   URI is defined as a default entry-point for requesting the links
   hosted by a server.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-core-link-format-13.txt

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

This Internet-Draft can be retrieved at:
ftp://ftp.ietf.org/internet-drafts/draft-ietf-core-link-format-13.txt

The IETF datatracker page for this Internet-Draft is:
https://datatracker.ietf.org/doc/draft-ietf-core-link-format/

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 24 May 2012 00:39:04 +0200

The recently submitted draft-ietf-core-link-format-13.txt is intended to reflect IETF last call and in particular the IESG comments.

Drafts resulting from such a process have often been simply been published as RFCs without consulting the WG again.
However, the responsible AD and the chairs all believe it is a good idea to give the WG one more round to look at the result.

We are therefore announcing a one-week "WG review period" for the updated draft:

	http://tools.ietf.org/html/draft-ietf-core-link-format-13

Some additional resources:

1)
	http://datatracker.ietf.org/doc/draft-ietf-core-link-format/history/

gives you some visibility into what happened in the IETF/IESG process, and what the DISCUSSes and COMMENTs were that the IESG provided.

2)
	http://tools.ietf.org/rfcdiff?url2=draft-ietf-core-link-format-13&url1=draft-ietf-core-link-format-11

shows what changed between the version we submitted to the IESG and the result of this process.
As you can see, what mostly changed apart form editorial clarification was the selection of informal and formal description techniques that are in use for the format and for the query syntax.
Fortunately, some nice recently published documents like the definition of Origin (RFC6454) and URI templates (RFC 6570) made this job a bit more pleasant.

So, please do have a look, and tell the mailing list until

	2012-05-31, 12:59 UTC

whether there are remaining or new problems.
(Please also do send a quick notice if you had a look and didn't find any problems.)

Grüße, Carsten

---

From: "Rahman, Akbar" <[email-masked]>
Date: Mon, 28 May 2012 16:14:03 -0400

Hi Carsten/Zach,

I reviewed -ietf-core-link-format-13.txt.  I found it to be overall a very well written and useful I-D, and support it's advancement in the RFC process.  I did however have the following three points as questions/comments for you to consider:

1) Use of the term "CoRE"
My understanding is that WG names (e.g. Section 1) should generally NOT be included in RFC track I-Ds as the WG will end at some point while the RFC document is permanent.  But in this document you use the term "CoRE" extensively.  Did you consider using the term "CoAP" instead?

2) In section 2.1, point (c), it is not clear to me what the "document" is referring to in the sentence?

3) The use of the "hosts" relation type is missing in the examples (section 5).  It would be very useful to add an example using this relation.  Can you add one example that uses "hosts"?

Thanks,

Akbar

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Carsten Bormann
Sent: Wednesday, May 23, 2012 6:39 PM
To: [email-masked] WG
Subject: [core] WG review period for: draft-ietf-core-link-format-13.txt

1)

2)

	2012-05-31, 12:59 UTC

Grüße, Carsten

_______________________________________________
core mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/core

---

From: Zach Shelby <[email-masked]>
Date: Tue, 29 May 2012 08:31:46 +0300

Akbar,

Thanks for taking another look. See comments in-line:

> My understanding is that WG names (e.g. Section 1) should generally NOT be included in RFC track I-Ds as the WG will end at some point while the RFC document is permanent.  But in this document you…

CoAP would not make sense in this case, as this Link Format is not dependent on CoAP, it can be used equally as well over HTTP. I don't consider "CoRE" to be just the name of this working group, but "Constrained RESTful Environments" I consider to be a useful term to define the environment are solutions are solving problems in. Thus the term would live on regardless of the working group.

> 2) In section 2.1, point (c), it is not clear to me what the "document" is referring to in the sentence?

Right, for HTTP folks that means the representation returned to you as a result of your request. So if I GET /.well-known/core the set of links returned in the response is the "link format document". Maybe for our readers we should;

s/document/representation? 

> 3) The use of the "hosts" relation type is missing in the examples (section 5).  It would be very useful to add an example using this relation.  Can you add one example that uses "hosts"?

"hosts" is the default relation type for this link format, thus every link in the examples without an explicit rel= attribute is a "hosts" link. Does that need to be said explicitly in the beginning of the examples section maybe?

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

---

From: "Dijk, Esko" <[email-masked]>
Date: Tue, 29 May 2012 11:29:14 +0000

Dear Carsten, Zach,

I see one main issue in the draft. An attribute can have multiple values e.g.
  REQ: GET /.well-known/core
  RES: 2.05 Content
   </temp>;rt="temperature-c";if="http://www.example.org/myapp.wadl#sensor mysensor"

If I query this server for a "mysensor" interface as follows:
  REQ: GET /.well-known/core?if=mysensor

I won't get the expected /temp resource in the result, because value matching is done bitwise identical to the "if" string value between the double quotes. Or is my argument wrong here? It seems this needs more explanation in the draft - e.g. if using multiple values is reserved for some special cases where querying is not used.

regards,
Esko

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Carsten Bormann
Sent: Thursday 24 May 2012 0:39
To: [email-masked] WG
Subject: [core] WG review period for: draft-ietf-core-link-format-13.txt

1)

2)

        2012-05-31, 12:59 UTC

Grüße, Carsten

________________________________
The information contained in this message may be confidential and legally protected under applicable law. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, forwarding, dissemination, or reproduction of this message is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.

---

From: Zach Shelby <[email-masked]>
Date: Tue, 29 May 2012 15:42:11 +0300

Esko,

> I won't get the expected /temp resource in the result, because value matching is done bitwise identical to the "if" string value between the double quotes. Or is my argument wrong here? It seems th…

Good question. When multiple values are included in rel=, rt= or if= attributes (regardless of the attribute), those are treated as separate values logically. So your /temp link above has two separate if= attribute values, "http://www.example.org/myapp.wadl#sensor" and "mysensor". When a query is made for if=mysensor then that is compared against each value of if= associated with your links, and in this case it would match the link. 

Seems that was not clear, so I agree we need to add some clarification text to the Query Filter section. I will make a ticket and propose some text.

Zach

---

From: "Dijk, Esko" <[email-masked]>
Date: Tue, 29 May 2012 13:44:46 +0000

Thanks Zach, clear to me.  I agree the text needs to be updated to reflect this functionality.

E.g. an implementer may be surprised about his CoAP client queries GET /.well-known/core?if=mysensor and gets back 
  </temp>;rt="temperature-c";if="http://www.example.org/myapp.wadl#sensor mysensor"
where the "if" string is *not* bitwise identical to the query value.

Also the text 
  "any target attributes notated as quoted-string are interpreted as defined in
   section 2.2 of [RFC2616].  After these steps, a Complete Value String
   matches a target attribute if it is bitwise identical."
is not correct then it seems. if="http://www.example.org/myapp.wadl#sensor mysensor" is a quoted-string, so should be interpreted as one entity according to RFC2616 unless I'm wrong.

Esko

-----Original Message-----
From: Zach Shelby [mailto:[email-masked]] 
Sent: Tuesday 29 May 2012 14:42
To: Dijk, Esko
Cc: Carsten Bormann; [email-masked] WG
Subject: Re: draft-ietf-core-link-format-13: querying in multi-valued attribute cases

Esko,

Zach

---

From: "Dijk, Esko" <[email-masked]>
Date: Tue, 29 May 2012 13:52:46 +0000

Dear Zach, Carsten,

here are further review comments, all editorial. For the rest I'm ok with the contents of the link-format draft.

* Section 4.1 - terminology
"or any other link-extension name"
is " link-extension name" the right term? This concept is not explicitly defined. There is "link-extension" from the ABNF but this includes the full key=value thing. Same comment for "link-param name". Could be clarified; e.g. "link-extension parameter name" or so.

* Section 2.1
"
 (a)  The context URI is set to the anchor parameter, when specified,
        or
 (b)  Origin of the target URI, when specified
 (c)  Origin of the link format document's base URI.
"
the word "or" is missing behind (b);
Also in (b) "when specified" could be wrongly interpreted as an origin that has to be specified while it is about target URI that can be specified or not.
Clearer is e.g. : "Origin of the target URI, when the target URI is specified"

* the difference between terms "relation type" and "relation attribute" and "relation parameter" is not fully clear yet. Perhaps this could be improved by adding definitions or following the terms from RFC5988 closer?
"relation attribute" is used as a term, but not defined explicitly, nor in RFC5988. (There "relation type" and ""rel" parameter" are used).
It seems the link-format I-D does not yet explicitly state that relation attribute is in fact the attribute with the "rel" parameter name.

* Examples section: it could refer first explicitly to core-coap and that you need it to understand the examples.
E.g. ct=40 occurs in examples, only clear with reference to core-coap.

* terms in 4.1
"
Complete Value String
Prefix Value String
"
-> on first reading, it looks like these terms are not defined anywhere. On second reading, it looks that this first mention is meant to be their definition. Maybe some editorial improvement here? (E.g. "X, defined as Y, ...")

* Examples section
"[GET /.well-known/core?rt=temperature-c] would request resources
        with the name TemperatureC. "
TemperatureC -> temperature-c

* Since relation types "alternate" and "describedby" are used in examples, the text might point the reader again to rfc5988 for their definition.

* Some examples have RES: 2.05 "Content" while others have RES: 2.05 Content without quotes

* Maybe section 7.3 should refer per what document registration is done, or what registry is involved (RFC 4288?)

Esko

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Carsten Bormann
Sent: Thursday 24 May 2012 0:39
To: [email-masked] WG
Subject: [core] WG review period for: draft-ietf-core-link-format-13.txt

1)

2)

        2012-05-31, 12:59 UTC

Grüße, Carsten

---

From: "Rahman, Akbar" <[email-masked]>
Date: Tue, 29 May 2012 16:44:24 -0400

Hi Zach,

Thanks for the feedback.  Please see my SUGGESTIONS in-line below.

Akbar

-----Original Message-----
From: Zach Shelby [mailto:[email-masked]] 
Sent: Tuesday, May 29, 2012 1:32 AM
To: Rahman, Akbar
Cc: Carsten Bormann; [email-masked]
Subject: Re: [core] WG review period for: draft-ietf-core-link-format-13.txt

Akbar,

AKBAR: OKAY.  BUT YOU SHOULD AT LEAST REMOVE THE REFERENCE TO THE "WORKING GROUP" IN FIRST SENTENCE OF SECTION 1 (INTRODUCTION) AND REFRAME THE PARAGRAPH AS YOU DESCRIBE ABOVE.

AKBAR: I WOULD PREFER "REPRESENTATION".

AKBAR: I THINK THE USAGE FOR HOSTS AND RULES FOR "HOSTS" HAS TO BE MENTIONED EXPLICITLY IN SECTION 5 FOR CLARITY.  ALSO IN PREVIOUS VERSIONS OF THE I-D THERE WAS SOME USEFUL TEXT IN 7.2 WHICH IS NOW DELETED (I.E. "..and by default the context of the links is the server at coap://authority from which /.well-known/core was requested.").  WHY WAS THIS TEXT DELETED FROM SECTION 7.2?

Thanks,
Zach

---

From: Zach Shelby <[email-masked]>
Date: Wed, 30 May 2012 10:40:20 +0300

Hi Akbar,

All useful suggestions. I will make a ticket to fix these, and will also look to re-insert that example text (or similar) from 7.2 that you found useful.

Thanks,
Zach