Esko Dijk
2018-03-26 12:51:35 UTC
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
act on behalf -> act on behalf of
"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?
-> 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.
-> 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?
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.
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)"
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.
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.
Figure 4: lifetime 'lt' should be '1' according to the text, not '0-1'
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..
See https://en.wikipedia.org/wiki/Class_diagram#Association 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.
"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.
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.
4
(re-e)starting -> (re)starting
RD directory servers -> resource directory servers
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?
Edge Router (6LBR) -> Border Router (6LBR)
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"
"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.
________________________________
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.
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
act on behalf -> act on behalf of
"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?
-> 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.
-> 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?
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.
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)"
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.
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.
Figure 4: lifetime 'lt' should be '1' according to the text, not '0-1'
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..
See https://en.wikipedia.org/wiki/Class_diagram#Association 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.
"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.
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.
4
(re-e)starting -> (re)starting
RD directory servers -> resource directory servers
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?
Edge Router (6LBR) -> Border Router (6LBR)
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"
"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.
________________________________
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.