Re: [core] Comments on draft-hartke-t2trg-coral-reef-03

[Jim Schaad <[e-mail]>]

-----Original Message-----
From: Klaus Hartke <[e-mail]> 
Sent: Friday, December 6, 2019 7:38 AM
To: Jim Schaad <[e-mail]>
Cc: [e-mail]; [e-mail] WG <[e-mail]>
Subject: Re: [core] Comments on draft-hartke-t2trg-coral-reef-03

Hi Jim,

thanks a lot for your comments!

> * I am having a problem with you saying that you are defining a new 
> well-known resource.  "/.well-known/core" has already been defined.  
> It would be better to say you are expanding the capabilities I think.

This is mostly due to the fact that I haven't looked much yet into how RFC 6690 and -coral-reef would coexist on the the same well-known path, so at the moment -coral-reef is just assuming that it's alone in the universe (see also the disclaimer in [1]). Of course, this cannot stay like that if we want to work towards a WG adoption. Then we should figure out whether -coral-reef should take over the resource entirely (possibly with a section describing the "legacy" format (with an opportunity to "fix" that)) or whether -coral-reef should be presented as an extension to RFC 6690 or something else.

> *  In the first example in the document (page 4), I believe that you should
> be able to return "ct TBD3" as part of the "/sensors" resource.   This may
> or may not be covered by this document so I am not sure if you think 
> it would be allowable or not.  Specifically, I believe that any place 
> you can currently use application/link-format you should be able to 
> use REEF

Not sure. Not every resource that has a Link Format representation behaves like </.well-known/core>. But in this case (the example was stolen from [2]) I think the intention was that </sensors> functions like a kind of "mini" resource directory for additional resources on the server. So it would indeed make sense here to use -coral-reef for that too. I wonder if/how we should signal to a client that </sensors> not just happens to have a representation in format TBD3 but also implements the -coral-reef interface.

[JLS] I don't know that I have dealt with anything that did link-format that was not a directory type thing.  Yes it would only make sense for those things which are directory like.

> * At the end of section 2.1, second to last paragraph - The last 
> clause in the last sentence has a problem with matching the pronoun 
> back to the correct subject.  On first read I matched one back to 
> schema not to the details.  I think that use of a semicolon would fix this problem.

OLD:

   The example contains links to three resources of interest on the
   server: </sensors>, </sensors/temp>, and </sensors/light>.  For
   </sensors>, a content format hint ("ct") and a title ("title") are
   provided as resource metadata.  For both </sensors/temp> and
   </sensors/light>, a resource type ("rt") and an interface description
   ("if") are provided.  Additionally, two links are provided with
   further detail on </sensors/temp>: one to a schema describing this
   resource ("describedby") and one to an substitute ("alternate").

NEW:

   The example contains links to three resources of interest on the
   server: </sensors>, </sensors/temp>, and </sensors/light>.  For
   </sensors>, a content format hint ("ct") and a title ("title") are
   provided as resource metadata.  For both </sensors/temp> and
   </sensors/light>, a resource type ("rt"), and an interface
   description ("if") are provided.  Additionally, two links are
   provided that provide further details on </sensors/temp>: a link to a
   schema describing this resource ("describedby") and a link to a
   substitute ("alternate").

Does that fix it for you? Otherwise I'd need a bit of help since I'm not a native speaker :)

[JLS] Looks like you have the same for both OLD and NEW, however this fixes the issue.

> * In section 2.2, the registration interface is currently missing the 
> query parameters.  The big ones would be ep (endpoint name) and d 
> (domain), you should not need base because that can be represented in the CoRAL document.
> About the time I got to section 5.2 on the second pass, I realized 
> that you did not deal with endpoint registration and queries at all.  
> This is a needed feature.

This is a feature that I don't understand. What does it do and why is it needed?

[JLS] Endpoint and Domain provide a way to give a "name" to an endpoint and to associate that name to the entry in the RD.  For a third party, among other things this means that you only need to find the name of the endpoint to get and update the entry in the resource directory.  You do not need to both remember and share the location path to other entities.  If you think that this is not clear in the RD document, this should be raised as an issue to get better text there.

> *  There should however be a statement that the link for an rd-item 
> when registering MUST NOT only be a path comment.

I assume you mean you do not want relative references. But, if I want to register a resource that has the same authority (IP address/DNS name and port) as the resource directory, why should I not be able to register that using a relative reference?

[JLS] Yes I meant component not comment.  In theory there is no reason why you should no be able to do so.  In practice it is going almost always be an indication that there is an error in the registration.  The only entity this should be true for is the RD itself.

> * I think there should be a statement that only the first base 
> directive can include schema + authority information.  This is because 
> you are only supposed to register resources for one entity at a time.

-coral-reef currently doesn't make this restriction/assumption. If you have, for example, a commissioning tool that registers the resources of lots of servers in a resource directory and wants to register all of them as a single unit, then I don't see why shouldn't be allowed to do so (given proper authorizations).

[JLS] Well - you are going to have a hard time returning the location-path to each of those different servers that you just registered into the RD.

> * Section 3 - I am not sure you want to use the word "identifier" in the
> description of title.  That is not normally how I think of a title.   I
> would probably also use "title" rather than "label" in both paragraphs.
>
> * Section 3 - you need to give me something to better distinguish 
> between #type and #ct as they both seem to say the same thing to me.
>
> * Section 3 - you need to say something about how to deal with #ct for 
> multiple values.  I am not sure about #if

Section 3 currently sources its list of items from different places, such as [3] and [4], and hasn't seen much work yet. For example, the word "identifier" was just copied from [4]. Let's go through the list sometime (maybe in a CoRE virtual interim?) and decide what to keep, how to name it (I'm not a big fan of the acronyms), and how to describe it.

[JLS] Sounds reasonable.

> * Section 3 - I think that you should have all of the tags in this section.
> For example rd-item and rd-unit.

rd-item and rd-unit are not resource metadata vocabulary, so I wouldn't add them to this section. But, yes, having a combined list of all the vocabulary used in the document somewhere would be nice. Maybe as an appendix?

[JLS] You may not thinking of them as resource metadata vocabulary, but they are vocabulary for -reef.  As such they need to have a description someplace that is easy to find and having all of the vocabulary in a single location is very useful.    Titling the section  "Reef Vocabulary" and then having subsections would also be a way to address you grouping issue.

> *  General - I know that this is supposed to be what is going to 
> happen, an ?rt= query option is going to be the same as reef#rt, but I 
> don't think there is anyplace in this document that makes that statement.

Section 4.2.2 [5] currently says:

   On success, the server returns a 2.05 (Content) response with a
   representation of the list of resources (see Section 4.1.1), but
   containing only the subset of links that has resource metadata of
   type <http://coreapps.org/reef#rt> with the specified text value.

[JLS] That does not answer my question.  Do rt and <http://coreapps.org/reef/#rt> map to the same information, and if so where is this stated so that I don't get confused about other things that have similar looking names.  This is going to be really an issue if you start getting rid of abbreviations and go to <http://coreapps.org/reef/#resource-type> instead because the strings no longer match.  Given that the RD needs to support arbitrary strings in the link format, knowing if the list is closed or open ended in some manner helps.  

** Jim


Klaus

[1] https://tools.ietf.org/html/draft-hartke-t2trg-coral-reef-03#section-1
[2] https://tools.ietf.org/html/rfc6690#section-5
[3] https://tools.ietf.org/html/rfc6690#section-3
[4] https://tools.ietf.org/html/rfc8288#section-3.4.1
[5] https://tools.ietf.org/html/draft-hartke-t2trg-coral-reef-03#section-4.2.2