Subject: [netmod] WG last call comments

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 07 May 2009 16:47:42 -0400

Having noticed the WG last call on YANG, I have done another read 
through he document.  The following comments are all relatively minor or 
editorial.  They are about presentation of information in the document, 
not about technical choices made by the working group.

Minor:
1) In the definition of Mandatory node in section 3.1, it talks about a
container node with a "mandatory" child.  What if that mandatory child
is within a choice construct (probably indirectly, and the choice itself
is not explicitly marked mandatory), i.e. in the choice case A is such
that there are no mandatory parts, but case B contains constructs which
are Mandatory.  Is the parent mandatory?

2) In section 5.6.4 defining the syntax for announcing conformance, 
there appears to be some ambiguity in the intended structure.
It appears that arbitrarily many revision, module, and feature parameter 
are allowed, in any order.
Presumably, a module parameter is required before any revision, 
deviation, or feature parameters?
And revision, deviation, and feature parameters are to be interpreted as 
applying to the most recent prior module parameter?
What does it mean if there are multiple revision parameters after a 
module parameter (I.e. after the only module parameter, or between one 
module parameter and the next.)
The feature parameter allows a comma separated list of feature names. 
If there are multiple feature parameters that apply to the same module 
parameter, are the features to be concatenated, overwritten, first 
parameter kept?  (The obvious meaning in that case is to concatenate, 
but it does not say so.)
And what of multiple deviation parameters?

3) The reference for schema discovery (section 5.6.5) should point 
somewhere.  If it can not point at least to an I-D, then the section 
should be removed.  (I think we can get away with making it an 
informative reference, although it is right on the edge.)  It might make 
sense to remove it anyway, and just include the text in the Schema 
Discovery document.

4) Is it intentional that submodule is defined to occur at most once, 
and module does not have such a restriction?  (in section 7.)

5) In section 7.5.8 on the use of edit-config with containers, there 
seem to be a number of pieces that are not described.  Some of these are 
covered by the general description in netconf (for example on the 
relationship between merge and replace.)  Even so, a sentence here 
saying that would be helpful.
However, there is one case where the netconf stuff does not seem to help.
On "replace," if the node exists, what happens with regard to child 
nodes present in the XML and the datastore?  (It seems clear that the 
recursive behavior of "replace" is somewhat different from "replace" on 
the parent, and for good reasons.)

6) Should there be some sort of comment in the description of choice 
that the given rules are not sufficient to ensure that all choice 
definitions are unambiguous, and it is the model developer's 
responsibility to ensure that if the distinction matters that the 
various combinations of possible defaults is unambiguous?  (I am 
thinking about a choice without an explicit default, where two of the 
branches are such that they can legally exist with with just default 
values (they have no mandatory components.)  I think that the rules as 
written permit ambiguities, and that the system could not determine 
which branch was actually the case.  In particular, if someone was 
trying to get the config with-defaults, the system might not know which 
case to use.  (It would likely be a situations where the two cases, in 
default, resulted in the same behavior.  But one XML needs to be returned.)

7) In the definition of the RPC element, I presume that there are 
constraints on the use of the "grouping" element?  When groupings appear 
directly in the rpc element, they can not define any data components 
other than input or output?  And the collection of grouping, input, and 
output elements can not define more than 1 input and 1 output?  (If so, 
this does mean that the cardinality limit on grouping directly in rpc is 
0..2, not 0..n, I think.)

8) In defining notifications, is it part of the definition to indicate 
that certain fields are supposed to be used to represent values from 
other parts of the data tree (like the src address of the packet in 
error, or the power level of the misbehaving laser, or the temperature 
from the thermal senor...)  I think, if I am reading this right, that 
the plan in netmod is to simply define the information to be reported, 
and to use description clauses to indicate where the information really 
comes from?  A little more explanation of this in the notification 
section would be helpful.

9) The text on updating a module specifies that updates must not cause 
interoperability problems in the case where a client using the old 
module talks to a server using the new module.  The allowed changes 
include expanding the set of legitimate values.  (contract the valid set 
would be as bad or worse.)  But this seems to mean that a client may 
receive values that it considers invalid from the server.  It seems to 
me that somewhere there ought to be a statement that says "although 
clients must be aware of teh definition of valoid values for generating 
configuration data, they must also be prepared to receive apparently 
invalid values from the server if teh server working with a newer 
version of a module.

Editorial comments:
The type statement is forward referenced at the end of 4.2.4.  It 
should be to section 7.4, not to section 9.

In the example of special strings in 6.1.3.1, just to confirm the 
expected, would it be worth including "'"?

Since section 7.1.6 (The include Statement) is reference for submodules 
as well as modules, the text of the first sentence probably ought to read:
   The "include" statement is used to make content from a submodule
   available that submodules parent module, or any other submodules
   of that parent module.
(The text in the first sentence currently says it makes it available 
only to modules.)

Section 7.8 The list statement, in the sentence after the introductory 
paragraph says "A list entry is uniquely identified by the values of the 
list's key."  However, the first sentence in 7.8.2 says that the "key" 
statement is optional for state data.  So shouldn't the sentence in 7.8 
be somewhat qualified?  ("if defined" at the end of the sentence might 
well suffice.)

It would probably be nice to remind readers in section 7.8.2 (The list's 
key Statement) that while fields in containers can not be used as key 
fields, leafs defined in groups can be used.  (This gets around my 
biggest concerns with the requirement that the key elements be direct 
leaf elements in the list.)

Should the definition of the reference statement (7.19.5) say something 
about the syntax?
Related to that, the text leaves me completely puzzled as to what 
"reference" elements are for.  I thought for a while they were related 
to the leafref type.  But they aren't.  I think that there ought to be 
some more text in 7.19.4 telling the reader just what the content is 
supposed / expected to be, other than "string" as defined by the ABNF.

It seems odd and confusing that a range statement is not required to 
have its values in canonical form.  At least, it would seem useful to 
have a sentence saying that, and stating why it is so.

In section 10 on Updating a Module, it says that obsolete definitions 
MUST NOT be removed.  In the status section it says that obsolete is 
specifically for things that can be removed, as deprecated is for things 
that can not be removed?  I think the difference is between "removed 
from specification" and "removed from implementation.  A few extra words 
here would avoid confusing the reader.  (Something like "Although 
explicitly obsolete elements may be removed from implementations, they 
must not be removed from specifications so as to avoid rendering other 
definitions syntactically invalid.")

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 10 May 2009 23:15:42 +0200 (CEST)

Hi,

> are Mandatory.  Is the parent mandatory?

Note that the text says "mandatory child" not "mandatory descendant".
So if a container has a choice as the only child, the container is
mandatory if and only if the choice is mandatory.

> It appears that arbitrarily many revision, module, and feature
> parameter are allowed, in any order.

Hmm.  The intention is at least that there can be at most one of those
parameters.  This can be solved in two ways:

  1) tighten up the ABNF to:
         parameter       = [revision-parameter]
                           [module-parameter]
                           [feature-parameter]
                           [deviation-parameter]
     i.e. explicit zero-or-one, in specified order, or

  2) keep the ABNF, but add text that says "each parameter can appear
     at most once".
     i.e. keep the current order-does-not-matter parameter list

Personally, I prefer 2.

> The feature parameter allows a comma separated list of feature
> names. If there are multiple feature parameters that apply to the same
> module parameter, are the features to be concatenated, overwritten,
> first parameter kept?  (The obvious meaning in that case is to
> concatenate, but it does not say so.)

The 'feature-parameter' simply list which features of the module the
device implements.  Do we need more text added to 5.6.4.2 (and
5.6.4.3)?

> should be removed.

I realized after hitting the submit-button that I forgot to remove
this Open Issue.  This section will be removed, and the relevant text
added to the schema discovery draft.

> and module does not have such a restriction?  (in section 7.)

No.  I suggest we model 7.2 after 7.1 and change section 7.2:

OLD:

  The "submodule" statement is used to give the submodule a name, and
  to group all statements which belong to the submodule together.

  The "submodule" statement, which MUST be present at most once, takes
  as an argument an identifier which is the name of the submodule,
  followed by a block of substatements that hold detailed submodule
  information.

NEW:

  The "submodule" statement defines the submodule's name, and groups
  all statements which belong to the submodule together.  The
  "submodule" statement's argument is the name of the submodule,
  followed by a block of substatements that hold detailed submodule
  information.  The submodule name follows the rules for identifiers
  in ^identifiers^.

> seem to be a number of pieces that are not described.  Some of these
> are covered by the general description in netconf (for example on the
> recursive behavior of "replace" is somewhat different from "replace"
> on the parent, and for good reasons.)

7.5.8 says:

      If the operation is "replace" and the node exists, all child nodes
      not present in the XML are deleted, and child nodes present in the
      XML but not present in the datastore are created.

Doesn't this cover your question?

> which branch was actually the case. 

Could you clarify this, preferably by giving an example which you
think is ambiguous?

> constraints on the use of the "grouping" element?  When groupings
> appear directly in the rpc element, they can not define any data
> components other than input or output? 

A grouping can never define 'input' or 'output'.  Note that the
grouping statement *defines* the grouping (like typedef defines a
type), so having a grouping under the rpc just defines a grouping
which can be reused in the substatements to 'input' and 'output'.

> from the thermal senor...) 

If you want to make such a reference, you can use a 'leafref' type.

> I think, if I am reading this right, that
> and to use description clauses to indicate where the information
> really comes from?  A little more explanation of this in the
> notification section would be helpful.

Could you suggest some text to add?

> include expanding the set of legitimate values.  (contract the valid
> set would be as bad or worse.)  But this seems to mean that a client
> may receive values that it considers invalid from the server.  It
> seems to me that somewhere there ought to be a statement that says
> "although clients must be aware of teh definition of valoid values for
> generating configuration data, they must also be prepared to receive
> apparently invalid values from the server if teh server working with a
> newer version of a module.

Yes, you are right.  Depending on the query, clients must also be
prepared to receive XML elements they don't understand; either from
some other namespace that the client does not know about (when
augment has been used), or from the same namespace (when the server
has a newer version).
> should be to section 7.4, not to section 9.

Fixed.

> expected, would it be worth including "'"?

Do you mean like this:

     "'"   - string containing a single quote

> Since section 7.1.6 (The include Statement) is reference for
> submodules as well as modules, the text of the first sentence probably
> ought to read:

Ok.  I changed it to this:

  The "include" statement is used to make content from a submodule
  available to that submodule's parent module, or to another submodule
  of that parent module.

> paragraph says "A list entry is uniquely identified by the values of
> the list's key."  However, the first sentence in 7.8.2 says that the
> "key" statement is optional for state data.  So shouldn't the sentence
> in 7.8 be somewhat qualified?  ("if defined" at the end of the
> sentence might well suffice.)

Ok, I added "if defined".

> It would probably be nice to remind readers in section 7.8.2 (The
> list's key Statement) that while fields in containers can not be used
> as key fields, leafs defined in groups can be used.  (This gets around
> my biggest concerns with the requirement that the key elements be
> direct leaf elements in the list.)

Would this text work (as a new sentence last in the first paragraph):

  The leafs can be defined directly in substatements to the
  list, or in groupings used in the list.

> Should the definition of the reference statement (7.19.5) say
> something about the syntax?

It says something more than just "string":

   The "reference" statement takes as an argument a string which is used
   to specify a textual cross-reference to an external document, either
   another module which defines related management information, or a
   document which provides additional information relevant to this
   definition.

This text is taken from rfc 2578 (the REFERENCE clause in SMIv2).

If more text is needed, I welcome any suggestions.

> have a sentence saying that, and stating why it is so.

It seems to me that requiring this to be in canonical form would not
help interoperability, but help readers of the module.  As such, this
is probably a good rule to add to the YANG usage guidelines draft.

> specifically for things that can be removed, as deprecated is for
> things that can not be removed?  I think the difference is between
> "removed from specification" and "removed from implementation.  A few
> extra words here would avoid confusing the reader.  (Something like
> "Although explicitly obsolete elements may be removed from
> implementations, they must not be removed from specifications so as to
> avoid rendering other definitions syntactically invalid.")

Section 10 explicitly says "removed from modules" (and section 10 is
about updating *modules* (not implementations)).  But 7.19.2 just says
"removed".  I suggest we clarify 7.19.2 to read:

  - "obsolete" means the definition is obsolete and SHOULD NOT be
    implemented and/or can be removed from implementations.

/martin

---

From: "Joel M. Halpern" <[email-masked]>
Date: Tue, 12 May 2009 11:28:19 -0400

Thanks for the response.  Most of them look good.  Here are 
amplifications on a few points.

Thank you,
Joel

> "Joel M. Halpern" <[email-masked]> wrote:
...
> Doesn't this cover your question?

The question is what happens with child nodes present in both the XML 
and the datastore.  Neither of the two clauses covers that.  (Given the 
subtleties, even if you think the existing netconf definition covers it, 
please restate here.)

> Could you clarify this, preferably by giving an example which you

After looking at this some more, I believe that the intended meaning has 
no ambiguity.  But this relies on the question of the scope of 
identifiers under cases in a choice.  Looking back at 6.2.1, leaf and 
container names are scoped to their "parent node."  If the case is the 
parent node, then one could get name duplication across cases within a 
choice, and all sorts of confusion could result.

I believe the intent is that for name scoping purposes, the scope is the 
entire choice, not the individual case.  Is there somewhere we can say 
that?  (In 6.2.1. would seem right.)

> which can be reused in the substatements to 'input' and 'output'.

Sorry, I don't follow.  The input and output substatements each 
explicitly allow "uses."  That's fine.  But the rpc element itself 
allows "uses."  If groupings can not define input or output, then a 
grouping can not appear directly under rpc, and should not be listed there.
>> 8) notifications ...

"A notification will typically be defined to include the indication of 
what the problem is, and any relevant data.  The relevant data is 
defined as leaf elements in the notification.  The semantics that these 
are copies of other information in the datastore, for reporting 
purposes, is captured in the relevant description clauses."

...

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 12 May 2009 22:36:46 +0200 (CEST)

Hi,

"Joel M. Halpern" <[email-masked]> wrote:
> Thanks for the response.  Most of them look good.  Here are amplifications on a
> few points.
> 
> Thank you,
> Joel
> 
> Martin Bjorklund wrote:
> > Hi,
> The question is what happens with child nodes present in both the XML and the
> datastore.  Neither of the two clauses covers that.  (Given the subtleties,
> even if you think the existing netconf definition covers it, please restate
> here.)

Ok, I see what you mean.  I will get back to you...

> After looking at this some more, I believe that the intended meaning has no
> ambiguity.  But this relies on the question of the scope of identifiers under
> cases in a choice.  Looking back at 6.2.1, leaf and container names are scoped
> to their "parent node."  If the case is the parent node, then one could get
> name duplication across cases within a choice, and all sorts of confusion could
> result.
> 
> I believe the intent is that for name scoping purposes, the scope is the entire
> choice, not the individual case.  Is there somewhere we can say that?  (In
> 6.2.1. would seem right.)

6.2.1. tries to say that:

   o  All leafs, leaf-lists, lists, containers, choices, rpcs, and
      notifications defined within a parent node or at the top-level of
      the module or its submodules share the same identifier namespace.
      This namespace is scoped to the parent node or module, unless the
      parent node is a case node.  In that case, the namespace is scoped
      to the parent node of the case node's parent choice node.

Note the last two sentences.

> Sorry, I don't follow.  The input and output substatements each explicitly
> allow "uses."  That's fine.  But the rpc element itself allows
> "uses."

Where do you see that?  "uses" is not listed in 7.13.1, and it not
listed in the ABNF rule for rpc-stmt.

> "A notification will typically be defined to include the indication of what the
> problem is, and any relevant data.  The relevant data is defined as leaf
> elements in the notification.  The semantics that these are copies of other
> information in the datastore, for reporting purposes, is captured in the
> relevant description clauses."

But this seems too restrictive - leafrefs can be used to have a formal
reference to config / stats data.  An example is given in 9.9.6:

     notification link-failure {
         leaf if-name {
             type leafref {
                 path "/interfaces/interface/name";
             }
         }
         leaf index {
             type leafref {
                 path
                   "/interfaces/interface[name = current()/../if-name]"
                 + "/ifIndex";
             }
         }
     }

/martin

---

From: WashamFan <[email-masked]>
Date: Wed, 13 May 2009 10:15:59 +0800

>  > >> However, there is one case where the netconf stuff does not seem 
> to
>  > >> help.

IMO, if the operation is "replace" and the node exists, the server should
substitute the node in the datastore with the corresponding node in the
XML. I.e., all child nodes are deleted, then all child nodes present in the XML
are created.

Any comments?

washam

---

From: "Joel M. Halpern" <[email-masked]>
Date: Tue, 12 May 2009 22:50:45 -0400

With regard to the two items that you observed there was already text 
for, you are correct.  I am apparently going blind.

With regard to the notifications, it may be that I am misudnerstanding 
what including a leafref in a notification will do.
Will it include in the notification the value of the leaf pointed to? 
If so, that would be perfect and there is no need for the text I sent. 
I had understood that it would send a reference (an identifier, 
presumably xpath?) for the leaf. [More depending upon meaning...]

With regard to the edit-config on containers, I look forward to the 
additional clarification.

Thank you,
Joel

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 13 May 2009 08:48:05 +0200 (CEST)

Hi,

"Joel M. Halpern" <[email-masked]> wrote:
> With regard to the notifications, it may be that I am misudnerstanding what
> including a leafref in a notification will do.
> Will it include in the notification the value of the leaf pointed to? If so,
> that would be perfect and there is no need for the text I sent. I had
> understood that it would send a reference (an identifier, presumably xpath?)
> for the leaf. [More depending upon meaning...]

Yes, when the leafref is encoded in XML, the value of the leaf pointed
to is included.  In 9.9.6, there is an example of the XML encoding
for the notification I sent in the previous email:

     <notification
       xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
       <eventTime>2008-04-01T00:01:00Z</eventTime>
       <link-failure xmlns="http://acme.example.com/system">
         <if-name>eth0</if-name>
         <index>2</index>     <--- This is the leafref
       </link-failure>
     </notification>

/martin

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 13 May 2009 10:42:40 -0400

Perfect.  Thanks.

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 13 May 2009 22:11:41 +0200 (CEST)

> Ok, I see what you mean.  I will get back to you...

After looking at this section, and the other sections describing
NETCONF edit-config processing for the different node types, I think
it would be best to simplify this section a bit.  I suggest we model
it after 7.8.6 (lists), but add the explicit reference you suggested
in your first comment on this issue:

NEW:

7.5.8.  NETCONF <edit-config> Operations

   Containers can be created, deleted, replaced and modified through
   <edit-config>, by using the "operation" attribute (See [RFC4741],
   section 7.2) in the container's XML element.

   If the container has a "presence" statement, it MAY be implicitly
   created if it does not exist, even if the operation is "none".

   If a container has a "presence" statement and the last child node is
   deleted, the NETCONF server MAY delete the container.

(I would also add this explicit reference to section 7.2 of 4741 to
the other edit-config processing sections.)

/martin

---

From: WashamFan <[email-masked]>
Date: Thu, 14 May 2009 10:52:00 +0800

>     created if it does not exist, even if the operation is "none".

I can envision that, if a P container belongs to default data,
when its parent is going to be created, it is going to be created
along. I assume it is the case where a P container MAY be 
implicitly created.

But I can't figure out how this is related to operation "none". To
my understanding , "none" is for hierarchy level check for 
incoming configuration data and won't trigger any real action.

Can you elaborate? Or maybe a example helps.

Thanks,
washam

---

From: Andy Bierman <[email-masked]>
Date: Wed, 13 May 2009 20:05:15 -0700

> Can you elaborate? Or maybe a example helps.

Thanks for pointing this out.
I object to that last sentence you quoted!

It goes against the original intent of default-operation = 'none'.
If the 'active operation' is 'none' then the node MUST exist
in the database already, or a 'data-missing' error is generated.
This is by design.  The operator should use 'replace' or 'merge'
as the default-operation instead of 'none', if they want this
behavior.  Since 'merge' is the default, there doesn't need
to be any special case for 'none' wrt/ NP containers.

>>     deleted, the NETCONF server MAY delete the container.

This is backwards.
It should be 'does not have a "presence" statement'.
The agent never deletes empty P-containers, just NP-containers.

>>  the other edit-config processing sections.)

Andy

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 13 May 2009 23:20:03 -0400

If the rules for creating, deleting, or replacing parts are exactly 
those from NETCONF, (which they ought to be) then your proposed text 
seems the right approach.

Yours,
Joel

---

From: WashamFan <[email-masked]>
Date: Thu, 14 May 2009 11:20:46 +0800

>  >>     If a container has a "presence" statement and the last child 
> node 
>  >> is

But if the intent is what you said above, I am afraid it should
have been 'MUST' instead of 'MAY' in Martin's text.

washam

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 14 May 2009 09:43:20 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> > along. I assume it is the case where a P container MAY be implicitly
> > created.
> > my understanding , "none" is for hierarchy level check for incoming
> > configuration data and won't trigger any real action.

I agree that this CLR should be removed.

So the text would become:

NEW:

  Containers can be created, deleted, replaced and modified through
  <edit-config>, by using the "operation" attribute (See ^RFC4741^,
  section 7.2) in the container's XML element.

  If a container does not have a "presence" statement and the last child
  node is deleted, the NETCONF server MAY delete the container.

/martin