On Thu, Oct 15, 2015 at 10:37:49PM +0200, Martin Bjorklund wrote: > > > * 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.] > > To start with, I think we should define client and server more > generically than just NETCONF: > > server: An entity that provides access to YANG-defined data to a > client, over some network management protocol. > > client: An entity that can access YANG-defined data on a server, > over some network management protocol. >
Yes, we should definately open things up so that RESTCONF clients and servers are covered. > > * 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? > > How about: > > This non-normative section is intended to give a high-level > overview of YANG to first-time readers. OK > > * 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. > > We changed this to "leaf instance" after discussion with Lada. I > think it makes sense to mention that it is supposed to contain data > like an integer or string, so I think I prefer to keep this text as > is. I think the document uses 'leaf' in different meanings; sometimes a leaf is a 'leaf schema node instance' and sometimes a leaf is 'any leaf of the tree'. This is what got me started here but perhaps the context is clear enough (hence the 'perhaps simplify'). > > * 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. > > But aren't all sections normative unless we say so? Otherwise it > seems we should start every section by saying that it is either > normative or not. OK > > * 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. > > It's actually not only data nodes, it is also rpc, actions, > notifications, identities. How about: > > The "namespace" statement defines the XML namespace that all > identifiers defined by the module are qualified by in the XML > encoding, with the exception of identifiers for data nodes, action > nodes, and notification nodes defined inside a grouping (see ^uses^ > for details). The argument to the "namespace" statement is the URI > of the namespace. OK > > * 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. > > I think we can say "If the constraint evaluates to false, the string is > passed as <error-message> in the <rpc-error> in NETCONF." Other > protocols have to define how these fields are used. OK > > * 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). > > This makes sense. I think the last paragraph can be replaced with: > > If a non-presence container does not have any child nodes, the > container may or may not be present in the XML encoding. OK > > * 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. > > Or maybe we should simply remove the last paragraph completely? For > NETCONF, RFC 6243 details how leafs with defaults are handled. Well, yes, but then readers may not know about RFC 6243. Perhaps state that leaf nodes containing a default value may not be present in the XML encoding and point to RFC 6243 for further details how NETCONF handles leafs with defaults (and I think the reference to RFC 6243 would be informative). > > * 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? > > > Hmm. NETCONF and RESTCONF use quite different encodings of rpcs and > their output. > > NETCONF: > > <rpc message-id="101" > xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> > <rock-the-house xmlns="http://example.net/rock";> > <zip-code>27606-0100</zip-code> > </rock-the-house> > </rpc> > > <rpc-reply message-id="101" > xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> > <ok/> > </rpc-reply> > > RESTCONF: > > POST to .../rock-the-house > > <input xmlns="http://example.net/rock";> > <zip-code>27606-0100</zip-code> > </input> > > result: 204 no content > > > Maybe it would have been better to have a common encoding, like: > > <rock-the-house xmlns="http://example.net/rock";> > <input>...</input> > </rock-the-house> > > and > > <rock-the-house xmlns="http://example.net/rock";> > <output>...</output> > </rock-the-house> > > but this cannot be done now. > > So, maybe the simplest solution would be to rename the section to > "NETCONF XML Encoding"? You mean section 7.14.4? Well, OK... Too bad these RPC encodings are actually different. Out of curiosity, was there a specific reason not to use <rock-the-house xmlns="http://example.net/rock";> <zip-code>27606-0100</zip-code> </rock-the-house> in the RESTCONF POST or did this "just happen"? > > * p105 > > > > Again, the proposal is to separate the XML encoding of notifications > > from the details how notifications work with RFC 5277. > > Also notifications are encoded differently in RESTCONF and NETCONF. Hm. > > * 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? > > Yes, maybe we can just say: > > Data nodes representing configuration are part of configuration > datastores. Yes. > > * 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'. > > I don't really see what you mean. Can you suggest new text? See above, I think 'leaf' sometimes means an instance of a leaf schema node and sometimes it means all leaf instances of the data tree. Or I am confused. I think here you mean 'all leaf instances of the data tree' and not the subset of all 'instances of a leaf schema nodes'. /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 netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
