Hi,
I have read through draft-ietf-netmod-rfc6020bis-07 (except section 9.
Built-In Types). Overall, the document is in a good shape. I spotted a
number of editorial issues or a number of issues where we could try to
seek a clearer separation of NETCONF specifics. (I plan to read
section 9 as well but I assume this is less important since there
likely are not many changes from RFC 6020 in this part.)
I am indicating the paper number below for each comment/suggestion.
* p8:
s/XML has been/XML have been/
s/how the data model/how a data model/
s/represented in/encoded in/
* p9:
s/names means/names mean/
* p11:
s/the module faithfully/a module faithfully/
I am also wondering why we use device and server. It seems we use
these terms interchangeably. If so, for clarity, I would suggest to
use a single term, that is s/device/server/ and perhaps explicitly
state that unless stated otherwise server means a server providing
access to a YANG defined data tree.
* p12/p13
We import 7 terms from RFC 6241. Would it make sense to copy the
necessary text in order to avoid a too strict binding to RFC 6241?
In particular, 'client' and 'server' means NETCONF client and server
if we import from RFC 6241 but this may be a bit narrow given that
we have RESTCONF as well. In an ideal world, we would factor out
core architectural concepts but the best we can do is likely to
define core concepts inline, pointing out where they are the same.
The idea is to loosen the coupling to RFC 6241. Example:
OLD
o datastore: an instantiated data tree
NEW
o datastore: A conceptual place to store and access information.
A datastore might be implemented, for example, using files, a
database, flash memory locations, or combinations thereof.
[Matches the definition in RFC 6241.]
* p13
Does the term 'mandatory node' really deserve its own subsection? I
understand that there are references to section 3.1 but would
reference to section 3 not work as well?
* p13
s/used for other/used with other/
* p14
s/encoded in NETCONF operations/encoded on-the-wire/
* p14
s/of NETCONF data models/of data models for network management
protocols such as NETCONF,/
And I suggest to remove the following sentence since it is not
really needed.
The data models described by YANG are designed to be easily
operated upon by NETCONF operations.
* p15
s/read-only access/read-only access [RFC6643]/
* p15
I am not sure why the last paragraph in section 4.1 is needed. In
the first setence, I would remove 'Like NETCONF' and in the second
sentence I am not sure what we are saying given that there is NACM.
I would definitely remove the second sentence and if the first
should be kept, I would likely move it up since it is a fairly
general statement. But I think removing the whole paragraph is the
simplest solution since it is not essential.
* p13
Would it make sense to add a sentence right at the beginning of
section 4 stating that section 4 is intended to provide orientation
for the first time reader but that section 4 is not normative?
* p15
With the previous in mind, I suggest to remove "This progressive
approach handles the inter-related nature of YANG concepts and
statements. A detailed description of YANG statements and syntax
begins in Section 7." from the text right below 4.2. Note that
Section 7 is actually Section 6 (but Section 5 has also important
normative content).
* p16
s/four types of nodes/four types of data nodes/
* p16
Perhaps simplify:
OLD
A leaf instance contains simple data like an integer or a string. It
has exactly one value of a particular type and no child nodes.
NEW
A leaf data node has exactly one value of a particular type and no
child nodes.
* p16-p25
Should this be 'XML Encoding Example' instead "NETCONF XML Example'?
This does not seem to be NETCONF specific.
* p25
s/XML representation/XML encoding/
* p25
s/operations' names/operations' name/
* p25
s/node in the data hierarchy/data node/
* p28
Start section 5 by saying that this section defined language
concepts and that it is normative, e.g.
This normative section defines core language concepts.
* p29
s/its contents are unchanged/its content is unchanged/
* p37
s/following shows valid data/following XML encoding shows valid data/
* p35
I think there should be a citation of I-D.ietf-netconf-yang-library
where this module first appears.
* p46
The text concerning module names is a repetition from section 5.1.
To avoid introducing inconsistencies, perhaps replace the repeated
text with a reference to section 5.1?
* p49
Is the text in section 7.1.3 correct when it says all identifiers
defined by the module? I mean, schema node identifiers are
namespaced by module names and their prefixes. And data node
identifiers are using the namespace in the XML encoding. Here is
an attempt of a rewrite:
The "namespace" statement defines the XML namespace that all data
node identifiers defined by the module are qualified by in the
XML encoding. Data node identifiers defined inside a grouping are
an exception q(see Section 7.13 for details). The argument to
the "namespace" statement is the URI of the namespace.
* p53
Another repetition of the module/submodule name requirements, does
it make sense to avoid repetition?
* p61
Should the text in 7.5.4.1 and 7.5.4.2 say explicitly that we talk
about NETCONF when we refer to <rpc-error>? Or should the text try
to be more generic, saying that the respective fields will be
carried in error message in protocols that use YANG? It is actually
somewhat opaque what an error-app-tag is or how it should be used.
* p63
Should the last paragraph in 7.5.7 be factored out into its own
subsection titled "NETCONF <get> and <get-config> Operations"? The
text is not really anymore about XML encoding (which may be used
with RESTCONF). Or the text is actually about the encoding but
should be written to simply state that non-presence containers can
be pruned in encodings (without restricting this to NETCONF).
* p67
Similar to the comment for p63. Perhaps the right way is to phrase
this in such a way that is simply says leaf nodes containing a
default value may not be present in the XML encoding. Simply remove
NETCONF <get> or <get-config> specifics.
* p72
s/an unspecified order/an order determined by the system/
Note that a description clause may actually define how the system
has to order elements and hence 'unspecified order' seems wrong.
* p97
The text in 7.14 talks about NETCONF specifics, namely the <rpc>
element and the "rpcOperation" substitution group. Perhaps move this
down into a specific section defining the mapping of YANG RPCs to
NETCONF <rpc>s.
* p100
The XML encoding text starts with detailing NETCONF specifics.
Would it make sense to separate the XML encoding of the rpc and its
input/output from the specifics how the RPCs fit into NETCONF's
<rpc> system?
* p102
The XML encoding section again mixes XML encoding of the node
hierarchy with NETCONF specifics how an action is invoked using
NETCONF's <rpc> system. I suggest to factor this into two different
sections.
* p105
Again, the proposal is to separate the XML encoding of notifications
from the details how notifications work with RFC 5277.
* p120
The text in section 7.21.1 talks about NETCONF specific operations.
Is this actually necessary? Can the purpose of the config statement
not be described by referring to general concepts such as
configuration datastores instead of using protocol specific
operations?
* p123
Is there a special reason why the text uses 'notification instance
data tree' instead of just 'notification data tree'?
* p123
"All leaf data values MUST match the type constraints..." may be
read as 'all data nodes that contain values' or 'all instantiations
of nodes defined by the leaf statement'.
* p192
The Acknowledgements section may need some updates.
/js
--
Juergen Schoenwaelder Jacobs University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
Fax: +49 421 200 3103 <http://www.jacobs-university.de/>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
