Subject: [netmod] YANG thoughts

From: "Joel M. Halpern" <[email-masked]>
Date: Mon, 18 Aug 2008 15:24:48 -0400

Having read the document, below are some comments that the working group 
may find helpful.  After talking with folks, it seemed worthwhile to 
send them to the list.

The main thing that strikes me, as you can probably see in the comments,
is that this would have been easier to understand with a bit of
motivation.  There are a number of design choices which while
reasonable, seem odd.  I suspect that there are strong reasons for the
choices.  But they are not stated.

Comments:
The first thing that struck me was that the absolute insistence on
non-leafs not having values seemed strange.  It makes for much cleaner
XML.  And is not actually unreasonable.  But it is jarring to the reader.
It would also help if the sentence about datatypes being simple values
occurred earlier.  For a while I was wondering when one used a
collection of leafs and when one used a complex data structure.  Once I
hit the statement that datatypes are always simple values, this became
clear.

In describing the choice construct, (in 4.2.7, not the later formal
definition) it would be useful if the document showed where a choice
would go.   Is it free-standing, and referenced like "using", or does it
appear in a container as if it were a node?  (Yes, it is clear
later, but it leaves the reader wondering.)

It might be a good idea to indicate when "key" is first described
(4.2.2.4) whether a single leaf is always used as a key (so one uses
nested nodes for multiple indices) or whether multiple keys can be use
together. (I see later that you went for multiple keys.  Just say the
statement can list multiple keys in 4.2.2.4.)

The include /import rules seem designed to make life difficult.
1) It is not clear what happens if the same module is imported more than
once by different parts of the include tree.
2) The prohibition against circular includes and imports means that
folks writing these things have to be very careful.  (I understand that
the basic answer is that if two pieces need to include or import each
other, then they should be one piece.  The point is that these rule
means that they HAVE to be one one piece.)
These rules presumably exist for good reasons.  But I suspect that some
explanation of the reasons will help the reader grasp the context
better.  And probably help the implementors do a better job.

Also, the distinction between import and include, with include only for
pieces that are part of the same module, and import for anything at all,
looks arbitrary.  It presumably isn't.  But as it stands it is at best
confusing.  Is there some subtle but substantive difference in what they do?

Given that the key-arg syntax in appendix D is a list of identifiers, it
seems that all of the leafs referenced by a key statment must be
directly contained in the list being keyed, and not in a nested
container (much less a nested list).   It would be sensible to actually
say this in 7.8.2.

7.8.3 (unique) and later 7.15 refer to things being in descendant form.
  But no text in this document says what descendant form is.  Could
something be put in the glossary section, even if this is a standard XML
term?  (If so, then the glossary can just say "XML term for ..., see ...
for a precise definition.)

Confusions:

The prefix statement within a module (as distinct from that used in an
import statement) appears to be advisory, even though it is mandatory,
and is described as "defining" the prefix for the module.  In practice,
it seems to be advise to anyone importing the module (either in xml or
YANG) as to what prefix they SHOULD use, if there is no conflict.  So it
appears never to be checked.  Am I missing something important about how
this statement works?

Personal prejudice:
The fact that leaf, and similar statements, have very restricted fields
allowed inside a "uses" makes me uncomfortable.  It seems that the
parser will need to understand that many things that are normally legal
are not allowed in that particular leaf (leaf-list...).

_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Aug 2008 23:32:11 +0200 (CEST)

Hi Joel,

> choices.  But they are not stated.

See the separate discussion on this issue.

> occurred earlier.

I don't see any obvious place to put this, do you have any
suggestions?

> For a while I was wondering when one used a

I will add a container wrapper element to the example.

> statement can list multiple keys in 4.2.2.4.)

Done.

> confusing.  Is there some subtle but substantive difference in what they do?

I will try to clarify this.

> container (much less a nested list).   It would be sensible to actually

The text in 7.8.2. currently says:

  Each such leaf identifier MUST refer to a child leaf of the list.

Is this clear enough?

> for a precise definition.)

No it's not a std term; its refers to the grammar rule.  I'll try to
clarify this.

> appears never to be checked.  Am I missing something important about how

The prefix MAY be used within the module to refer to local typedefs
and groupings, and MUST be used to refer to local extensions.

> are not allowed in that particular leaf (leaf-list...).

I agree with you, see e.g. the threads:
http://www.ietf.org/mail-archive/web/netmod/current/msg00088.html
http://www.ietf.org/mail-archive/web/netmod/current/msg00730.html 

/martin

---

From: "Joel M. Halpern" <[email-masked]>
Date: Tue, 19 Aug 2008 19:25:15 -0400

Comments in line...

> I don't see any obvious place to put this, do you have any

It would seem simple to add some text either to the second paragraph of 
4.1, or as an additional paragraph right after that. The second 
paragraph of 4.1 is where this first comes up.

Which lets me try to explain further my point about explanations. 
Mostly, my guess would be that this is simply a matter of adding a 
couple of sentences the first time a restriction or design decision is 
introduced.  This sort of explanatory text is very common in RFCs (and 
very rare in other standards body documents.)

..
>   Each such leaf identifier MUST refer to a child leaf of the list.
The issue here is probably as much in my head as in the document, and it 
is probably up to you folks.  However, I tend to see "child leaf of the 
list" and think of both direct and indirect children.  Partially this is 
simply because I have seen information group such that the necessary key 
is not a direct child.  (We defines structs whose components are 
themselves structs all the time.  While this can be flattened, that is 
not usually a good practice.)
...
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod