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

From: Klaus Hartke <[email-masked]>
Date: Fri, 6 Dec 2019 16:37:37 +0100

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.

> * 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 :)

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

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

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

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

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

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

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

---

From: Jim Schaad <[email-masked]>
Date: Fri, 6 Dec 2019 10:11:46 -0800

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

Hi Jim,

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

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

NEW:

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.

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

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

[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

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 7 Dec 2019 12:18:26 +0100

Jim Schaad wrote:
> [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.

There are two sides: the lookup interface and the registration
interface. On the lookup interface side, if you want to get all the
registered resources associated with one CoAP endpoint, I guess the
authority (IP address/DNS name and port) is the natural endpoint
identifier. On the registration interface side, you have the
registration units in -reef. If you want clients to give these units a
name, then you immediately run into namespace coordination problems.
So I think the best solution here is to let the server decide the name
of a registration unit. That indeed means you have to pass the
server-generated name around if want other parties to make
modifications, but the same applies to a client-generated name, no?

> [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 regi…

That seems like an issue of how you want to set up policies for your
resource directory, but not an interoperability issue.

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

On the lookup interface side, if multiple resources on different
servers match the query, then you'll need to return URIs to all those
different servers. On the registration interface side, if a
commissioning tool registers many resources on different servers at
once, then this single unit has only a single location in -reef.

Maybe this is part of the endpoint/domain thing that I don't understand...

> [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 ha…

There are four different namespaces here: The names of attributes that
RFC 6690 allows you to put in a Link, the name of query parameters
that RFC 6690 allows you to use for filtering, the name of query
parameters that -reef allows you to use for filtering, and the
resource metadata vocabulary in -reef.

* The list of attributes that RFC 6690 allows you to put in a Link is
basically open ended. There are a few attributes defined in RFC 6690
("rel", "anchor", "rev", "hreflang", "media", "title", "title*",
"type", "rt", "if", "sz") but any number of additional attributes can
be defined as long as the name conforms to the `parmname` rule and is
not "href". [1]

* The list of query parameters that RFC 6690 allows you to use is the
same as the list of attributes with the addition of "href" [2].

* The list of query parameters that -reef allows you to use currently
includes only "rt" [3] and "if" [4]. These map to
<http://coreapps.org/reef#rt> and <http://coreapps.org/reef#if>,
respectively [3][4]. The idea is that you can query by any other
metadata by using FETCH [5] instead of using GET with query parameter.

* The list of resource metadata vocabulary supported by -reef is open
ended. (The vocabulary "includes but is not limited to" the items in
section 3.)

Now there are those attributes defined in RFC 6690 and a bunch of
others that have been defined in a number of different places. When we
create the vocabulary for -reef, it would be nice if we had an
equivalent to each of them. But I think (and that was the conclusion
of a discussion with Christian a while ago) that we'll probably don't
want to do a mechanical mapping but rather a semantic one. For
example, have readable names instead of acronyms, do not use decimal
strings for integers, do not use whitespace-separated strings for
lists, etc. So the list of items in that mapping can only closed: If
you convert from Link Format to CoRAL, you really need to understand
each of the attributes you're converting.

Our conclusion was that this is a viable way forward even if new
attributes get defined in the future; those would just need to define
their mapping to existing or new CoRAL vocabulary. You can then easily
query by them using FETCH. For queries using GET with query parameter,
I guess we can choose if we want to have a fixed list or rather a
mechanism for discovering an open ended list of query parameter names
that are supported by a server.

Klaus

[1] https://tools.ietf.org/html/rfc6690#section-2
[2] https://tools.ietf.org/html/rfc6690#section-4.1
[3] https://tools.ietf.org/html/draft-hartke-t2trg-coral-reef-03#section-5.3.2
[4] https://tools.ietf.org/html/draft-hartke-t2trg-coral-reef-03#section-5.3.3
[5] https://tools.ietf.org/html/draft-hartke-t2trg-coral-reef-03#section-5.3.4