Subject: Re: [core] WG review period for: draft-ietf-core-link-format-13.txt

From: Zach Shelby <[email-masked]>
Date: Fri, 1 Jun 2012 10:25:58 +0300

On May 29, 2012, at 11:44 PM, Rahman, Akbar wrote:

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

OK.

>> 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? 
> 
> 
> AKBAR: I WOULD PREFER "REPRESENTATION".

I thought about this more, and "resource" is a better term. So c) would read:

Origin of the link format resource's base URI.

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

I added text in Section 5 explaining that, along with a note in Section 7.2. Thanks for pointing out that wasn't clear.

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: Zach Shelby <[email-masked]>
Date: Fri, 1 Jun 2012 10:49:25 +0300

Esko,

On May 29, 2012, at 4:44 PM, Dijk, Esko wrote:

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

I agree an example would help here. I have now added the following example to illustrate that this could happen:

   Note that relation-type attributes like rt=, if= and rel= can have
   multiple values separated by spaces.  A query filter parameter can
   match any one of those values, as in this example:

   REQ: GET /.well-known/core?rt=light-lux

   RES: 2.05 Content
   </sensors/light>;rt="light-lux core.sen-light";if="sensor"

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

I checked through the specification in Section 4.1 and it is actually correct. The text you are referring to only pertains to target attributes of quoted-string type, which are title or possible future link-extensions. The target attributes that can have multiple values are relation-type, and when Section 4.1 refers to "target attribute" each of the values contained in an rt=, if= or rel= is a target attribute. 

To further clarify this point, I added the following sentence to Section 4.1:

"Note that relation-type target attributes can contain multiple values, each value MUST be treated as a separate target attribute when matching."

Zach

> 
> 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,
> 
> On May 29, 2012, at 2:29 PM, Dijk, Esko wrote:
> 
>> 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.
> 
> 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
> 
>> 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
>> 
>> 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
>> 
>> _______________________________________________
>> core mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/core
>> 
>> ________________________________
>> 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: "Dijk, Esko" <[email-masked]>
Date: Fri, 1 Jun 2012 08:17:27 +0000

Ok, thanks.

> I checked through the specification in Section 4.1 and it is actually correct. The text you are referring to 
> only pertains to target attributes of quoted-string type, which are title or possible future link-extensions. 
> The target attributes that can have multiple values are relation-type, and when Section 4.1 refers to "target 
> attribute" each of the values contained in an rt=, if= or rel= is a target attribute.

Agree. It seems my confusion here comes from having a quoted string parameter value that is not a quoted-string.

> "Note that relation-type target attributes can contain multiple values, each value MUST be treated as a separate > target attribute when matching."

Ok. It should be "Note that relation-types target attributes..." with extra "s" at the end of relation-type. 

Esko

-----Original Message-----
From: Zach Shelby [mailto:[email-masked]] 
Sent: Friday 1 June 2012 9:49
To: Dijk, Esko
Cc: Carsten Bormann; [email-masked] WG
Subject: Re: draft-ietf-core-link-format-13: querying in multi-valued attribute cases

Esko,

   RES: 2.05 Content

Zach