Subject: Re: [core] draft-ietf-core-resource-directory-13 review - Sections 1-4

From: peter van der Stok <[email-masked]>
Date: Tue, 03 Apr 2018 10:07:23 +0200

Hi Esko,

thanks for the comments, below some reactions.
Most suggestions are taken over in github (excluding the ones that need 
some discussion)

Esko Dijk schreef op 2018-03-26 14:51:
> Dear RD authors,
> 
> Below are my review remarks for a partial review of RD-13: Sections 1
> to 4. I thought it good to submit now already, because any
> clarifications of the model (3.2 and 3.3) could help the understanding
> in doing further review of the rest of the document.
> 
> Best regards,
> 
> Esko Dijk
> 
> 3.1
> 
> accessing those resources -> accessing that resource
Not sure about that: the multicast cited in the phrase targets resources 
on multiple hosts.
> 
> act on behalf -> act on behalf of
Good catch
> 
> "Changes in the Resource Directory do not propagate automatically back
> to its source"  could use some clarification.
> 
> -> what is "its source" here exactly? Source of the change, or rather
> the web server that a registration entry is about?
The web server where the resource is located, as you suggest. will be 
clarified
> 
> -> in case the source is the registering web server itself, why would
> a change need to be propagated back to it at all? The server device is
> itself the initiator of the change.
It should NOT be propagated; and we want to make sure that THAT is 
understood.
> 
> -> in case the source is the CT, why would a CT's change to an RD
> entry need to be propagated back to the CT?
This is not the case.
> 
> 3.2
> 
> Figure 2 and other places in the document use "Target" as a term;
> because not everyone may be familiar with this abbreviation I would
> add "Target" in the Section 2 list of terms. Because [RFC 3986][RFC
> 6690] also do not define this abbreviation.

Good suggestion;
> 
> 3.3
> 
> The term "host" is now used here for the first time in the document
> while previously it was a (constrained) "web server". So in the bullet
> "a set of links belonging to the host" we could clarify this by
> changing to:
> 
> "a set of links belonging to the host (the web server whose resources
> are registered with an RD)"

Agree, clarifies things. Suggestion: s/The host/A web server/.
> 
> This links the two terminologies together nicely. "Host" is still a
> good term to use in 3.3 since we also introduce the "hosts" relation
> here.
In my suggestion the earlier equivalence between host noun and host verb 
is no longer present.
> 
> Last bullet on page 10: adapt formatting to show this bullet is part
> of the bullets-list above it. Now it looks as if the link attributes
> bullets list that starts on page 9 has only 3 bullets.

Right; numbering will solve this, but needs some "markdown" gymnastics
> 
> Figure 4: lifetime 'lt' should be '1' according to the text, not '0-1'
thanks, good catch
> 
> 
> Figure 4: Direction of reading the relations seems not always
> consistent. For example, I can read "group is composed of 1 or more
> registrations" or I can read "registration is composed of 1 or more
> groups". The latter is suggested by the placement of the "+1" in the
> figure, but this seems wrong, so best to have the "+1" text moved
> close to the  "registration" box to make it clear and use the UML
> class diagram way of directionality of relations.
> 
> In case the relation goes *both* ways then a solution is to apply the
> UML class diagram association notation, which means two numbers are
> placed next to a relationship line showing that 1 group can be
> associated to 1+ registrations and at the same time one registration
> can be associated to 0+ groups.

Absolutely agree. An oversight from our side.
> 
> See https://en.wikipedia.org/wiki/Class_diagram#Association [1] for
> some info and examples. I feel this UML class diagram is a better
> representation used most commonly in today's (IT) industry - and we'd
> better use a graphical representation that provides the expresssion of
> directionality that we need.
thanks for the reference
> 
> "A Group has no or one Multicast address attribute and is composed of
> 0 or more endpoints" -> that should be -> "A Group has zero or one
> Multicast address attribute and is composed of zero or more
> registrations"  if I read Figure 4. There is no line going from the
> "Group" box to an "Endpoint" box in the figure.

Right: caused by registration and endpoint equivalences: will change the 
text
> 
> 3.6
> 
> "Resource groups may defined to allow batched reads from multiple
> resources"
> 
> -> sentence is unclear whether this is 'an additional RD feature' as
> mentioned in the paragraph, or not. "Batch" does not come back in the
> RD draft. Also the concept of "resource groups" does not come back in
> the RD draft, we only have endpoint groups in Section 6.

@Michael may react here as well;
my proposal: remove the phrase. or change to: Groups may be defined to 
support efficient data transport.

> 
> 4
> 
> (re-e)starting -> (re)starting
(re-)starting
> 
> RD directory servers -> resource directory servers
-> RD server
> 
> the service with name rd._sub.._coap._udp -> here we specify a new
> subtype 'rd' under the service name 'coap'. If I read
> https://tools.ietf.org/html/rfc6763#section-16  correctly, then it is
> not mandatory to register this at IANA. Still it might be best to
> place this definition in a new Section 9.6 under 9 IANA
> Considerations, mentioning this subtype is specified here but not
> registered in the IANA Services Names registry because that's
> optional. What do you think?

I looked at the service name and transport protocol port number registry
The transport by coap still needs to be defined there and an expert has 
to be named.
@Carsten, I am sure that you have an opinion here.

> 
> Edge Router (6LBR) -> Border Router (6LBR)
OK
> 
> 4.1
> 
> "This information is needed when endpoints cannot discover the
> Resource Directory with a link-local multicast address because the
> endpoint and the RD are separated by a border Router"
> 
> -> I would suggest
> 
> "This information is needed when endpoints cannot discover the
> Resource Directory with a link-local or realm-local scope multicast
> address because the endpoint and the RD are separated by a border
> router"

Good suggestion

> 
> "The lifetime 0x0 means that the RD address is invalid and to be
> removed."
> 
> -> this information is already provided in the diagram below, in the
> text for the "Valid Lifetime" field. So I suggest removing here to
> avoid double definition of the same.

OK
> 
> -------------------------
>  The information contained in this email may be confidential and/or
> 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 email 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 email.
> 
> 
> Links:
> ------
> [1] https://en.wikipedia.org/wiki/Class_diagram#Association
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core