Subject: [netmod] comments on netmod-yang-05

From: Wes Hardaker <[email-masked]>
Date: Fri, 22 May 2009 08:45:13 -0700

As promised:

(my earlier comments about the draft being of great quality still apply,
of course)

I didn't get as far as I'd have liked (boy it's long) as 2 weeks just
wasn't enough to let me get all the way through it.

General:

- Many rules don't have MUSTs and SHOULDs and many do.  The wording
  seems to be fairly inconsistent with respect to this.  There are many
  points in the document where it's stated flatly that something is
  allowed or disallowed, and other points where the use of the word MUST
  is included.  I'm confused as to why MUSTs are present sometimes and
  not others.

- Much of the document seems to be written with the mindset of the
  (sub)module authors but don't discuss things in terms of
  implementations.  In fact many of the MUSTs/SHOULDs/MAYs seem to be
  directed at module authors rather than parser authors.  Maybe this is
  intentional.

- The substatement tables are *extremely* helpful.  Thanks for doing those. 

Section 4.2.3:
  The example adds a few things not discussed so far:
  "config true;" at the top: what's the default value?  It must be true
  based on the other examples?  You should state one way or the other
  (maybe in a // comment) that it's the default or not.

  Observed-speed could use a unit to be complete, but I actually think
  it should be left out because it hasn't been introduced yet.  I'm
  merely mentioning it so you can decide ;-)

Section 4.2.5:
  s/uint16/uint8/

Section 4.2.6 (I didn't get far enough into the document to check elsewhere):

  Can you use two "use" cases in a single statement.  What about "use"
  followed by other objects?  I suspect this is covered later.

Section 4.2.7:
  If mandatory isn't needed there (I don't think so) it should probably
  be removed till it's introduced later.

  Choosing beer as the example data I think would be better since it
  provides an example of an empty clause, which isn't shown until now.

Section 4.2.8:

  I found the first paragraph a bit oddly worded and hard to follow.

  I think the example could be a better one.  In the real world, which
  that example sort of models, uid's exist for every type of user not
  just !wheel classes.  Instead maybe a boolean "allow_login" instead?

Section 4.2.9:

  s#<name>acmefw-2.3</name>#<image-name>acmefw-2.3</image-name>#

  I'm actually don't think the example is a great one in the first place
  since image installs are one of the more complex cases of "when does
  it happen" and it's the reply sort of indicates "it's happening beyond
  now".  I'm fine with leaving it too, but a more concrete/less-fuzzy
  example would do better for the reader, IMHO.

Section 4.2.10:

  Change notification from status=up to down to make more sense.

Section 5.1:

  I found the whole modules/submodules thing confusing.  Part of it is
  the wording, part is the lack of understanding of exactly why you
  couldn't just use modules everywhere and prohibit certain operations
  at the same time, etc.  Don't get me wrong, I get it but I'm not sure
  the reader easily will.  Maybe a diagram would help?

  |----------|  import   |-----------|
  | moduleA  | - - - - ->|  moduleB  |
  |----------|           |-----------|
      |                   ^  include|
      V include           |         V
  |---------|           /     |---------|
  | submod1 |- - - - -/       | submod2 |
  |---------|    import       |---------|
      |        
      V include
  |---------|  
  | submod2 |
  |---------|  

  (badly done, but you might get the idea)

5.1.1:

  Use "p" as a prefix rather than "a" in the example for clarity against
  a:a.

5.3.1:

  I can't remember the version number decision if yang was "1" or "1.0"
  but ":1" looks odd after seeing ":1.0" in the netconf URNs.

5.4:

  It might be worth taking another editing hit on the second paragraph.

5.6.2:

  remove the "s" in '"features"' or put it after the "

5.6.4.3:

  I find the use of the second capability announcing the deviation a bit
  odd.  Specifically, the fact that the URL doesn't seem to matter
  (ending in my-deviations) but the module name afterward
  (?module=my-devs) is what is supposed to be matched on.  I'm sure
  readers will get it eventually but it took me a bit.  Not only that,
  there might be confusion about how to advertise multiple deviation
  modules.

5.6.5:

  Need to decide on or remove the open question marking

6.1.3:

  It should be noted that many definitions of "whitespace" include
  newlines, including standard regular expressions.

    # perl -l -e 'print "hello" if ("\n" =~ /\s/);'
    hello

  But this section deviates from that and discusses whitespace heavily
  but the examples show that newlines are exempt from being called
  whitespace (and you really mean just spaces and tabs).  (mostly in the
  paragraph "trailing whitespace is stripped..." which would remove the \n)

6.2.1:

  Again, the complexity associated with submodules and modules shows
  here.  I get it, as I said, but I doubt most readers will (quickly at
  least).

6.3:

  "Forward references are allowed in YANG".

     MUST be supported?

7.1:

  "A module SHOULD have the following layout:"

  What if it doesn't?  Does that mean a parser implementation doesn't
  have to accept it?  (this is an example of text written toward the
  author when it's the parser implementation that will be the most
  affected but yet the text doesn't describe the requirements of the
  implementation).

7.1.2:

  Is yang-version technically a string, decimal64 or binary blob?

7.1.6:

  "It is an error ..." -> an example of a missing MUST NOT?

7.1.9:

  I'd add the word "published" or "distributed" in front of "editorial
  change"

7.2:

  It'd be less a strain on IANA to have submodules prefixed with
  "parentmodule:" so that there exists a naming hierarchy for submodules
  such that there is no chance for collision.

7.5.3:

  Please please please don't hard-code the startup/running/candidate
  components into the yang document.  There is a definite possibility of
  future netconf extensions providing additional storage mechanisms and
  you don't want to rev yang because of it.

  Yang should stay out of specifying what datastores contain config,
  state or whatever.

Somewhere:

  You might add an example that uses current() somewhere

7.5.4.3:

  That example works well to show why maybe inverse logic would be more
  useful for must statements ;-)

7.5.8:

  This seems to blur the lines into the netconf territory and makes me
  nervous about future expansion.  Additionally, because it so netconf
  specific it doesn't allow parallel xml data of some other form.

Somewhere:

  Does the document discuss long-term issues with leaves?  IE, once a
  leaf name has been published it can never change in definition?

7.6.7:

  Before the colon add "placed into the previously defined "ssh" container:

7.7.5:

  What happens when a client requests data from a system ordered set of
  data, jumbles it (say makes it alphabetical according to how a user
  sorted it on the screen) and sends it back (eg, via a replace)?  This
  isn't discussed...

  1) can the server reject it?
  2) does the server have to parse it?
  3) is the server allowed to define internal semantics of it's own
     ordering?   (see large routing table implementations)

7.8.3:
  The wording isn't perfectly clear and could use a bit of improvement I
  think (and I'm sorry for never offering some direct suggestions).

  If unique constraints can be ignored when some of the nodes are not
  present with data then it might be worth adding a note about using the
  mandatory clause to prevent this.  It'd help the reader.

Sorry I didn't get farther into the document...

--
"In the bathtub of history the truth is harder to hold than the soap,
 and much more difficult to find."  -- Terry Pratchett

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 24 May 2009 16:02:38 +0200 (CEST)

Hi Wes,

>   directed at module authors rather than parser authors.  Maybe this is

Yes, in fact, I don't think any rules (except maybe the edit-config
rules) are worded specifically for implementations.  The rules try to
specify what is legal and illegal in the YANG language.

>   (maybe in a // comment) that it's the default or not.

The second sentence in 4.2.3 says:

  When a node is tagged with "config false",
  its subhierarchy is flagged as state data

So it implies that if the node is not tagged with config false, and
does not belong to such a subhierarchy, then it is is config data.

Section 4 is an overview section, so I would rather not go into all
the details here; the exact rules are covered later (in 7.19.1).

>   it should be left out because it hasn't been introduced yet. 

Ok, we'll leave it out :)

>   s/uint16/uint8/

Fixed.

>   followed by other objects?  I suspect this is covered later.

Yes, this is all fine.

>   be removed till it's introduced later.

Done.

>   provides an example of an empty clause, which isn't shown until now.

Done.

NETCONF XML Example:

  <food>
    <pretzel/>
    <beer/>
  </food>

>   I found the first paragraph a bit oddly worded and hard to follow.

How about this rewording, and simplification:

OLD:

  YANG allows a module to insert additional nodes into data models,
  including both the current module (and its submodules) or an
  external module.

NEW:

  YANG allows a module to extend data models with additional nodes.

>   s#<name>acmefw-2.3</name>#<image-name>acmefw-2.3</image-name>#

Fixed.

>   Change notification from status=up to down to make more sense.

But it is the admin-status that is up.

Since several people have been confused by this, I will add a leaf
"if-oper-status" with the value 'down' as well:

NETCONF XML Example:

  <notification
      xmlns="urn:ietf:params:netconf:capability:notification:1.0">
    <eventTime>2007-09-01T10:00:00Z</eventTime>
    <link-failure xmlns="http://acme.example.com/system"> 
      <if-name>so-1/2/3.0</if-name>
      <if-admin-status>up</if-admin-status>
      <if-oper-status>down</if-oper-status>
    </link-failure>
  </notification>

>   Use "p" as a prefix rather than "a" in the example for clarity against

Fixed.

>   but ":1" looks odd after seeing ":1.0" in the netconf URNs.

I don't think we ever had a discussion on this list about this, but
IMO "1" is sufficient.

>   remove the "s" in '"features"' or put it after the "

Removed the "s".

>   Need to decide on or remove the open question marking

It was decided to move this text to the monitoring draft.

>   paragraph "trailing whitespace is stripped..." which would remove the \n)

We can't simply s/whitespace/space or tab/.   

Do you think it would work if we write:

  If a string contains any whitespace characters (space or tab), 

or do we need more?

>   "Forward references are allowed in YANG".

This would direct the rule to implementations, where the current text
talks about what is legal.

>   affected but yet the text doesn't describe the requirements of the

The exact rules are specified in the grammar.  This text is there to
give the reader a quick overwiew of a what a module contains, instead
of having to figure it out from the grammar.  Would it be better to
write

  A module has the following layout:

or would that just make it worse?

>   Is yang-version technically a string, decimal64 or binary blob?

Or an uint8, uint64...  Does it matter what it is?

>   "It is an error ..." -> an example of a missing MUST NOT?

NEW:

Multiple revisions of the same module MUST NOT be imported.

>   I'd add the word "published" or "distributed" in front of "editorial

Added "published".

>   such that there is no chance for collision.

Does anyone else have an opinion on this?

>   Yang should stay out of specifying what datastores contain config,

In some places (such as in 7.5.3) I think we can replace the text
"<startup/>, <running/>, or <candidate/>" with a more generic "NETCONF
datastore", but in some other places, it gets tricky.  Specifically in
8.3.3 which discusses when data is validated.

In some earlier versions of the draft I just talked about "valid
configuration", with the intention that 4741 specifies that <running>
is always valid, and <candidate> is valid at commit time.  The current
text was added as clarification to this.

>   You might add an example that uses current() somewhere

There are two examples in 9.9.6.

>   specific it doesn't allow parallel xml data of some other form.

4741 leaves some questions open for the data modeling language to
decide.  I believe we must answer those questions in this docuement.
This section (and other similar) is very specific by ints nature.

>   leaf name has been published it can never change in definition?

Yes, see section 10, Updating a Module.

>   Before the colon add "placed into the previously defined "ssh" container:

Done.

>   2) does the server have to parse it?

Why would the server reject it?  Since there is no semantic order
defined, the client can send the data in any order, but the server is
free to re-order (but it doesn't have to).

>      ordering?   (see large routing table implementations)

I don't understand what you mean with "define internal semantics"?

> Sorry I didn't get farther into the document...

Thanks for your comments!

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 25 May 2009 11:44:01 +0200

> Does anyone else have an opinion on this?

Wes's concern is valid but the notation with the colon separator can be
confused with QNames in YANG modules. How about forbidding '.' (dot) in
module names and use it as the separator?

...

> Yes, see section 10, Updating a Module.

Not really, its definition can be changed in several ways: new values
may be allowed via the leaf's datatype that were not possible in the
original version, a default value may be defined, must statement removed
etc.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: "tom.petch" <[email-masked]>
Date: Tue, 26 May 2009 14:59:47 +0200

Sounds like a good idea to me.

(The question is in the middle:-) but to save having to search, it is
> Does anyone else have an opinion on this?
which arises from
> >   such that there is no chance for collision.

In fact, a very good one.

Tom Petch

----- Original Message -----
From: "Martin Bjorklund" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>
Sent: Sunday, May 24, 2009 4:02 PM
Subject: Re: [netmod] comments on netmod-yang-05

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