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

[Klaus Hartke <[e-mail]>]

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