Subject: [netmod] 2 more YANG details

From: Andy Bierman <[email-masked]>
Date: Mon, 21 Jul 2008 19:35:04 -0700

Hi,

I brought up these details on the yang mailing list,
but they got lost...

1) mandatory-stmt within a container

The container-stmt does not allow the mandatory-stmt
to be specified within it.  The rationale is that
the presence-stmt covers the same semantics.

Unfortunately, this is incorrect. Section 5.6 clearly
says that the presence-stmt simply indicates whether
the existence of an empty container node has meaning
within the data model or not.

The mandatory-stmt indicates whether the container must be
present in a valid configuration.  This has nothing to
do with the semantics of an empty container vs. a
non-empty container.

2) config-stmt within a choice

It seems perfectly valid to declare a choice node to
be config true/false, as other constructs that allow
the config-stmt.  This is the most direct way of
declaring a choice where all the case contents have
the same config-stmt value, which is the normal use-case.

This is especially important for child node from
uses or augment expansion, when the config value is designed
to be derived from the parent.

Andy

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

---

From: Phil Shafer <[email-masked]>
Date: Mon, 21 Jul 2008 23:16:46 -0400

>do with the semantics of an empty container vs. a

The idea is that a container is either organizational or meaningful.
It can be used to organize related nodes in a hierarchy, or its
presence can mean something to the config.  If it doesn't have a
specific meaning, why would you need it to be mandatory?  If
it does have a specific meaning, why would you want it to be
mandatory, since that would mean it would always be on, which
means that it's not meaningful?  So either way, a mandatory
container would not make sense.

>to be derived from the parent.

I understand the second sentence, and can agree that there's no
point in making config inside a choice illegal, but I don't get the
first sentence and the last sentence has me puzzled, since you only
need 'config' to turn it off.  Does your grouping want it off?  If
your choice turning it off?  Can you explain the use case?

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jul 2008 00:11:01 -0700

> container would not make sense.

Then rewrite the draft so this text is explained.
IMO, it is not important to the language structure
why a node is mandatory.  IMO, P and NP containers
do not add much value at all to YANG.  I would
also add instance-identifier and keyref to that cruft pile.

> your choice turning it off?  Can you explain the use case?

You just need a choice between 2 non-config parameters.
Expansion of groupings such as InetAddress type of nodes --
the same IP address field can be read-only or read-write,
depending on where it is used.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jul 2008 01:11:33 -0700

> container would not make sense.

Why doesn't this make sense?

   container name {
     mandatory true;
     leaf first {
       type string;
       mandatory true;
     }
     leaf middle {
       type string;
       mandatory false;
     }
     leaf last {
       type string;
       mandatory true;
     }
   }

IMO, it makes sense to say the <name> element must be present.
This element is used for encapsulation.  It is less important
which sub-fields comprise a 'name'.  The important thing
in the DM is that when 'name' is used in larger constructs,
it is mandatory.

This makes more sense to me than

   presence "The presence of this container indicates
             a person with a name.";

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 22 Jul 2008 12:38:04 +0200

> in the DM is that when 'name' is used in larger constructs,

Actually, the algorithm translating YANG to RELAX NG has to decide for
each container whether to wrap the corresponding element in <optional>
or not. From the YANG draft I understand the optionality rule for
containers as follows:

A container is optional iff
1. it is a container with presence, or
2. none of its descendant leafs has "mandatory true;" and none of 
   its descendant lists or leaf-lists has min-elements > 0, or
3. if such a leaf, list or leaf-list exists, it is enclosed in an   
   intervening container with presence.

So by this rule, container "name" in your example is implicitly
mandatory. But I agree this should be better explained in the YANG
draft.

>    presence "The presence of this container indicates

BTW, it would seem more logical, and symmetric to mandatory-stmt, to
have

    presence true;

or

    presence true {
        description "What the presence means...";
    }

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 22 Jul 2008 16:19:54 +0200

Hello,
As I understand it the mandatory statement for "name" is superfluous as it has at least one 
mandatory child.

Balazs

PS. I also dislike the whole presence stuff.

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
TSP System Manager
ECN: 831 7320                        Fax: +36 1 4377792
Tel: +36-1-437-7320     email: [email-masked]
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Phil Shafer <[email-masked]>
Date: Tue, 22 Jul 2008 11:33:56 -0400

>IMO, it makes sense to say the <name> element must be present.

The spec says:

    Since
    containers without a "presence" statement are implicitly created and
    deleted when needed, they are ignored when performing mandatory tests
    for leafs.  A mandatory leaf within such a container is mandatory
    even if the container's data node does not exist.

So you don't need to put mandatory on "name" at all, since this is
implicit in having a mandatory child.  You don't need (or want) a
presence statement on "name", since it has no specific meaning by
itself.

You need the presence statement when the container has a meaning
even if empty (which means it can't have mandatory children).
For example, if you have a set of protocols that are simple
to turn on but accept additional parameters, you could say:

    container mpls {
        presence "Enables MPLS on this interface";
        container filter {
            description "Filter content for MPLS traffic";
            leaf input {
                type keyref {
                    path /firewall/filters/name;
                }
                description "Name of the input filter";
            }
            // ditto for output
        }
    }

So <mpls/> is all that's needed to turn it on, but additional
configuration can be placed inside it.  The <filter> element has
no meaning by itself, but arranges the <input> and <output> nodes
in a hierarchical organization that keeps them together in context
and allows me to avoid calling them <filter-input> and <filter-output>.

    <interface>
      <name>so-0/0/0</name>   <!-- physical interface -->
      <unit>
        <name>0</name>      <!-- logical interface -->
        <family>            <!-- protocol families -->
          <inet>            <!-- turn on ipv4 with an address -->
            <address>
              <name>10.1.2.3</name>
            </address>
          </inet>
          <inet6/>          <!-- turn on other protocol families -->
          <mpls/>           <!-- ... that don't need additional -->
          <ccc/>            <!-- ... configuration -->
        </family>
      </unit>
    </interface>

Should we add this example to the draft?

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jul 2008 09:04:53 -0700

> presence statement on "name", since it has no specific meaning by

An optional container <mpls> can have mandatory leafs (and other nodes)
within it. So what.  That just tells me that if the container is
present, then it must have these nodes in it.  It does not tell
me if the <mpls> subtree is required on an agent or not.

With the current approach, you can never add (or expand via
uses/augment) a mandatory node to a container because it automatically
makes the entire path back to the root mandatory.  YANG does not
support the concept of a mandatory sub-structure within an
optional container:  "If <name> is used, then its 'first' and 'last'
leafs must be present, otherwise <name> is invalid.  But <name>
itself is not required to be present."

A list can have mandatory sub-nodes and that doesn't mean the
list entry itself is mandatory.  The min-elements controls
that, independent of the sub-nodes.  Why should the container behave
so much differently?

Andy

---

From: Phil Shafer <[email-masked]>
Date: Tue, 22 Jul 2008 11:59:10 -0400

Andy Bierman writes:
>IMO, P and NP containers

But we're looking to solve more problems than those you are currently
modeling.  We're looking to give sufficient feature richness,
flexibility and extensibility that this language can be used in
ways where you don't see value.  We're trying to incorporate features
from vendor DMLs (including mine) that have used features like
presence and keyrefs to power CLI and GUI features like completion
and drop-down boxes to give the user a better experience in the CLI
and GUI, and (more importantly) to remove sources of misconfiguration.

By producing richer meta-data, we allow folks to make richer
infrastructure that can enforce model rules in a more direct and
intuitive way.  By putting the user in a richer environment, we
help steer them in making proper choices, in helping them understand
their choice, and it detecting errors as early as possible.

If the keyref tells you the list of possible values, you can present this
list to the user (help them make the right choice) and give them an
error if their choice doesn't appear in the config (stop them from
making a config error).  If the config slips thru and is passed to
the device, instance-identifier gives the device a way of telling
you what you botched (helping you correct the error).

These features allow YANG to be useful outside the world of defining
IETF standards about how a management application talks to a device,
but that's a Good Thing.  It means folks can use it to produce
better functionality into their generic config browsers, giving
them better mechanisms for reducing configuration errors.  On the
device side, it gives better mechanisms for detecting errors from
mgmt apps, and allows the same infrastructure to be used in both
API and CLI bindings.  This reduces the cost of adhering to standards
and gives mgmt apps better access to the device proprietary informaton.

It's good news all around.  Promotions for everyone!

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jul 2008 09:21:05 -0700

> It's good news all around.  Promotions for everyone!

I sense from emails by DaveH and Wes that not everybody
involved in the WG fully understands YANG yet, and there
are concerns about the simplicity/power-feature trade-off.

I consider 'deep keys' to be a power-feature that is more valuable
than keyref.  YANG does not support encapsulation for information
hiding purpose very well at all.  The value of a <name> container
is that the entire <name> subtree can be treated as a handle
by applications, and reusable code can process the contents
of <name>, which can change over time (e.g., add initials,
title and suffix fields).

A grouping does not provide this feature, since the
node names of all the sub-fields can collide with other
siblings of the 'uses name;' statement.  But in YANG,
that is the only option, if you want to use 'name' as
a list key.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Tue, 22 Jul 2008 13:34:26 -0400

>me if the <mpls> subtree is required on an agent or not.

That's not how the spec reads.  If <mpls> has mandatory leafs,
that tells you <mpls> is required.

>makes the entire path back to the root mandatory.

Adding mandatory items will break the contract of the initial
module, since old module users won't know this added leaf
is mandatory.

>that, independent of the sub-nodes.  Why should the container behave

Because the non-presence container has no meaning.  It's purely
organizational, and can be discarded when empty.  An empty non-presence
container is meaningless.  In the previous example, the <family>
container contains the set of protocol families configured on an
interface.  If there are no protocol families, the empty <family/>
element carries no meaning in the configuration.

This varies greatly from lists, where the creation of a list element
means something.  The list instance carries a meaning.  The
non-presence container doesn't.  They are created and deleted as
needed, and so they don't carry the concept of "mandatory", since
their need to exist is dependent on their children.

We should definitely expand on this in the spec.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jul 2008 11:23:54 -0700

> that tells you <mpls> is required.

Given the usage of augments and groupings and complex nesting,
it might be non-trivial for the DM reader to determine this fact.

I do not like the asymmetry:

If I have a grouping with mandatory fields in it:

grouping name {
   leaf first {
     mandatory true;
     type string;
   }
   leaf middle {
     mandatory false;
     type string;
   }
   leaf last {
     mandatory true;
     type string;
   }
}

If I use this grouping in a list, it does not make
the list mandatory, but if I use it in a container, it does.

list X {
   key "last first";
   uses name;
   leaf extra-stuff {...}
}

container Y {
   uses name;
   leaf extra-stuff {...}
}

If container Y was reusable (i.e., in a grouping)
then it would be ripple upwards for containers
but not for lists and choices.  /Y is mandatory,
but /X/Y is not.   This is confusing.

IMO, it is easier and more intuitive for the readers
and writer to be able to control the optional/mandatory bit
at each node.  This is possible for list and choice,
but not container.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 22 Jul 2008 21:26:35 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> YANG does not

This is supported by making 'name' a presence container with 'first'
and 'last' mandatory leafs.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 22 Jul 2008 21:46:45 +0200 (CEST)

Hi,

> the list mandatory, but if I use it in a container, it does.

There are no such thing as "a mandatory list" and "a mandatory
container".  Presumably you mean that if you use the grouping above in
a non-presence container, this container will always be present in the
data store, but if you use it in a list, that doesn't magically create
a list entry.

> but /X/Y is not.   This is confusing.

Here's a simpler case:

  leaf a {
     mandatory true;
     ...
  }

  list interface {
     key name;
     leaf name { ... }

     leaf b {
       mandatory true;
       ...
     }
  }

Since 'a' is mandatory, /a must always exist.  'b' is also mandatory,
but you don't expect /interface/b to always exist, do you?

In the spec, it is explained like this:

    If "mandatory" is "true", the node must exist in a valid
    configuration if its parent node exists. [...]

> at each node.

Suppose I could make a container mandatory.  When would a writer want
to make a container mandatory?  A container does not have a value, so
it does not carry any information.  It can only provide some
information by its existance.  But if it is mandatory, it always
exists.  So when I see a container with mandatory true, I know that it
means that the container is purely structural.  But even though it's
purely structural, a manager has to create it even if it only has
optional children.  That would be pretty confusing IMO.

/martin

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 22 Jul 2008 22:51:24 +0200

Hello,
I agree with Andy. Creating an extra (mandatory) container is just a few bits or one XML line. 
That is far less work then understanding the concept of presence containers.

I like explicit statement: if I put mandatory there it is mandatory - simple.
Implied presence is a more complicated.

Balazs

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 22 Jul 2008 22:53:34 +0200

Hello,
What if 'name' does not have a real meaning, in which case we misuse the presence statement to 
indicate this construct of mandatory and optional nodes.
Balazs

---

From: Phil Shafer <[email-masked]>
Date: Tue, 22 Jul 2008 16:54:23 -0400

>Implied presence is a more complicated.

This gives us three classes of containers:
- those that mean something (presence containers)
- those that are optional and meaningless (non-presence containers)
- those that are mandatory and meaningless (new!)

I just can't see the value of saying "it doesn't mean anything
but it still has to be there".

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jul 2008 14:18:38 -0700

> but it still has to be there".

This 3rd class might be called encapsulation containers.
At the abstraction level of the 'name' construct,
it can make sense to decide if an instance of 'name' is
mandatory or optional.

IMO, encapsulation for complexity hiding and semantic/code reuse
is not meaningless.  YANG is very weak on information hiding
encapsulation -- no derived classes, no deep keys, no ability
to control containers top-down instead of bottom-up.

Andy

---

From: Balazs Lengyel <[email-masked]>
Date: Wed, 23 Jul 2008 10:48:00 +0200

> This gives us three classes of containers:
1) > - those that mean something (presence containers)
2) > - those that are optional and meaningless (non-presence containers)
3) > - those that are mandatory and meaningless (new!)
> but it still has to be there".
Case 2 and 3 are separate.

Case 2) is when the whole sub-tree is optional, but if it exists data inside MUST be there.
You might define the accounting server for your node as calls might or might not be charged, so 
the whole subtree is optional; only if you charge for the calls

Case 3) is when the container AND the whole sub-tree is mandatory, but I still want to put it 
under a container just to have a nice structure.
You must define a set of Home Subscriber Servers to act as a subscriber database as your IMS 
node will not wotrk without it

Balazs

---

From: Phil Shafer <[email-masked]>
Date: Wed, 23 Jul 2008 12:17:00 -0400

>the whole subtree is optional; only if you charge for the calls

By dig into the the question of "why is the whole sub-tree optional?"
If it have no independent meaning, why whould you make it?  If
you only make it to contian other nodes, then the need for the
child nodes is what makes you create it.  The non-presence container
has no meaning, and can be created and deleted as needed based on
the creation and deletion of the child nodes.

>under a container just to have a nice structure.

This container is merely organizational, but contains mandatory nodes.
Since the child nodes must exist, the existence of the container is
implicit.

>node will not wotrk without it

I don't follow this comment.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 23 Jul 2008 09:56:37 -0700

> the creation and deletion of the child nodes.

You seem to be focusing on direct, inline definitions
without considering object reuse.  When one attempts to use
groupings and containers for encapsulation and reuse,
YANG is not very powerful.  These 'building block'
sort of sub-structures need to be designed independently
of the parent context.  Some properties need to be inherited from
the parent node, by design.  IMO, 'mandatory' is one of them.
The parent node should decide if the child node is mandatory,
not the other way around.

IMO, it is more intuitive and reusable to be
able to define a container as mandatory true/false
in a top-down manner, rather than track down all the
child nodes, read all the presence-stmt clauses,
augment-when clauses, and eventually figure out
the mandatory status.

Of course the compiler can do that fairly quickly,
but not the DM reader or writer.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 23 Jul 2008 13:53:33 -0400

>not the other way around.

The parent uses refinement to make child nodes mandatory.

>but not the DM reader or writer.

So you want mandatory on containers as a hint to the reader, not
as this third kind of container?  Would it be a compiler error to
have a container that doesn't contain anything mandatory?  If not,
you still have to decide why you want a meaningless mandatory node.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 23 Jul 2008 11:15:41 -0700

> The parent uses refinement to make child nodes mandatory.

As written in the -00 draft.  Not cast in stone.
Uses refinement is by definition not information encapsulation,
and much more work than the mandatory-stmt.

> you still have to decide why you want a meaningless mandatory node.

I want the mandatory property to be relative to the containment
level, and the mandatory-stmt to be allowed in the container-stmt.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jul 2008 23:45:12 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> level

Does this answer Phil's two questions above?  Can you elaborate a bit?

> and the mandatory-stmt to be allowed in the container-stmt.

I got that one.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 24 Jul 2008 23:47:38 +0200 (CEST)

> not the other way around.

Are you proposing that if a container is marked as mandatory, *all*
its children are also mandatory?

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 24 Jul 2008 17:33:20 -0700

> its children are also mandatory?

no.

going back to the 'name' example:

grouping Name {
   container name {
     ....
   }
}

YANG has no way to control how Name is used in different
contexts.  If I had a data model designed with a 'default
administrator name', then the entire 'name' container
would be optional in that data model.

In another data model, the 'name' container may be mandatory
because there is no default to use instead.

But I can't design a grouping with a container in it,
because if that container has any mandatory fields,
it ripples up and makes the parent container mandatory.

Unless I could do this:

container admin {
   container sys-admin {
     uses Name {
       container name {
         mandatory true;
       }
     }
     uses Email;
   }
   container guest-admin {
     uses Name {
       container name {
         mandatory false;
       }
     }
     uses Email;
   }
}

Andy

---

From: Phil Shafer <[email-masked]>
Date: Fri, 25 Jul 2008 10:53:34 -0400

>         mandatory true;

So the issue that you want the above instead of refining
down to the level of the members of name, like:

container admin {
   container sys-admin {
     uses Name {
       container name {
         leaf last-name {   // Adding this one level
           mandatory true;
         }
       }
     }
 ...

Getting your desired outcome requires that you change the individual
leafs of name, not merely change name.  The current behavior give
you better control (for, say, scenarios where the first and last
names are mandatory but the middle is not), but does require that
the "use"r know which leafs need tuning.

IMHO, this isn't a horrible burden and the flexibility and control
of the current approach is more valuable than trying to answer the
question "it it's meaningless and empty, why is it mandatory?".

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 08:20:05 -0700

> the "use"r know which leafs need tuning.

no -- this misses the whole point of information hiding.
YANG has no real support for that. Groupings are pretty
worthless, since I have to be totally aware of the context
of the uses when writing the grouping, and also
need to be totally aware of the grouping contents
when I write the uses.  This isn't encapsulation at all.

> question "it it's meaningless and empty, why is it mandatory?".

You removed the rest of the example, which pointed out
that for the sys-admin, a name and an email address were
mandatory, but for the guest admin, just an email address
is mandatory.  The point of this contrived example
is that sometimes the DM writer needs to decide all-or-nothing
to use <name>, not just uses refinement of the sub-nodes.
Change <name> to <phone> if you want a better example.

CLI and SMIv2 are both awful when it comes to definition reuse.
Maybe YANG doesn't need to do any better, because nobody
cares about code/definition reuse for NETCONF.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Fri, 25 Jul 2008 11:46:22 -0400

>to use <name>, not just uses refinement of the sub-nodes.

I deleted the part because I thought it was making the same point,
which is that many times the "use"r of the grouping needs the
control, not the definer of the grouping.  In your example, the
grouping worked as written so the use statement had to refine it.

>Change <name> to <phone> if you want a better example.

Put <name> inside a <person> grouping and try to reuse that.
You need visibility into groupings to control these aspects.

>cares about code/definition reuse for NETCONF.

Control is more important that reuse, so being able to tune groupings
is more important that seeing them as all-or-nothing.  If you make
it all-or-nothing, its utility is demolished.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 09:05:04 -0700

> it all-or-nothing, its utility is demolished.

groupings are like XSD groups, which are basically assembly or C
language macro expansions.  You are correct in that this construct
provides no encapsulation features at all.

But C and XSD also have complex data types, that do provide
encapsulation features.  When I read the ipfix-psamp data model,
it sure looks like the authors wanted reusable complex types
in some places but were forced to use groupings instead.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 25 Jul 2008 20:38:40 +0200 (CEST)

> in some places but were forced to use groupings instead.

Can you make a proposal for what you want?  Are you suggesting that if
we allow mandatory in containers, then groupings are better complex
types??

/martin

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 11:48:50 -0700

> we allow mandatory in containers, then groupings are better complex

I do not want complex types.
I already said I don't like presence-stmt and
prefer mandatory-stmt instead.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Fri, 25 Jul 2008 16:35:41 -0400

>prefer mandatory-stmt instead.

The confusing part is that this isn't an "either-or".  These
are two different concepts.  The "precence" statement tells
us that the container has a meaning, and isn't merely there
to organize/scope other nodes.  Mandatory means the node must
exist in order for the configuration to be considered valid.
Consider:

               Does this container
               mean something if it appears?
                 yes   no
               +-----+-----+
Does this   yes|  A  |  B  |
container      +-----+-----+
have to     no |  C  |  D  |
exist?         +-----+-----+

A : meaningful and mandatory
B : organizational and mandatory
C : meaningful
D : organizational

D is the default case
C is the "presence" case
B is implicit if one child is mandatory
A is nonsensical  (If it means something, you can't force it to appear)

What you want (what I think you want anyway) is for
case B to be explicit.  This is unrelated to presence.

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 25 Jul 2008 22:49:22 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> Groupings are pretty
> of the uses when writing the grouping

Can you expand on this a bit?  Which "context of the uses" do I have
to be aware of when I write my grouping?

> and also
> when I write the uses.

You probably *should* be aware of the grouping's contents if you use
the grouping.  But nothing forces you to.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 14:04:42 -0700

>                mean something if it appears?

I want to be able to control a data model sub-structure
at any point in the tree.  I can do that for the
other interior node types (list and choice)
but not container.

You cannot turn the presence-stmt off in a uses refinement
like you can with must-stmt.

I do not agree that the presence-stmt adds much value at
all.  Why do we need a special description clause for this?
Why can't the description clause for the list itself say
what it means for an empty container to be present.
This special case makes YANG confusing, not better.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 25 Jul 2008 23:12:07 +0200 (CEST)

> other interior node types (list and choice)

Are you thinking about something else than turning off presence?

> all.  Why do we need a special description clause for this?

This can be solved by changing presence <string> to presence <bool>,
which we have discussed a couple of times before.

Can you think of a use case where you would like to change a presence
container into an organizational?

/martin

---

From: Phil Shafer <[email-masked]>
Date: Fri, 25 Jul 2008 17:25:44 -0400

>which we have discussed a couple of times before.

Perhaps the fix should be to use a different term for these
meaningful containers.  I suggest "block", but am open to
any other name.  This would give us:

container system {
    container services {
        block ssh {
            description "Secure Shell";
            presence "Enable SSH server";
            leaf rate-limit {
                description " Maximum number of connections per minute"
                type int {
                    range 1..250;
                }
            }
            container protocol-version {
                description "Define version of the SSH protocol are allowed";
                leaf v1 {
                    description "Allow SSH V1";
                    type empty;
                }
                leaf v2 {
                    type empty;
                    description "Allow SSH V2";
                }
            }
        }
    }
}

The CLI and GUI can "know" that system/services/ssh means
something.  The "presence" statement remains, to tell the
user what this statement's presence indicates.

This segregates meaningful containers away from organizational
ones, which isn't completely a good thing.

Another option would be to add a "type" statement to containers
that defaults to "organizational" but can be set to "meaningful"
when needed.  (Not hung up on the terms at all; totally open to
better words.)

    container ssh {
        type meaningful;  // "type presence"?
        ...
    }

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 25 Jul 2008 23:39:32 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> contexts. 

I don't understand this comment.  You can control how Name is used
down to every leaf in the refinment part of 'uses'.

> If I had a data model designed with a 'default

I don't agree with your terminology, but wouldn't you get the same

>      uses Email;

Since you marked the 'name' container mandatory, 'sys-admin' is now
"mandatory" etc.  

/martin

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 14:48:50 -0700

> down to every leaf in the refinment part of 'uses'.

That isn't really control over the <name> element at all.
Turning off every mandatory leaf is not user-friendly.

> Since you marked the 'name' container mandatory, 'sys-admin' is now

Yes, by the rules in the draft-00 I do not agree with, it is.
I would rather that sys-admin have its own mandatory-flag,
which is still default false.  I do not like
the presence-stmt and its special rules at all.

The draft says "if the parent is present", which makes
sense to me.  All the rules about ignoring this kind of
container or that kind, based on the sub-tree mandatory
flags and the presence-stmt -- it's seems too complicated
to be correct.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 15:04:48 -0700

>                     description "Allow SSH V2";

I am interested in the ability to create arbitrary-sized
building blocks, or sub-structures, out of containers.
They are not meaningless.  They provide permanent
name collision protection, so they are much more bullet-proof
when used in groupings.

What if I wanted protocol-version above to be a reusable
construct called SshProtocolVersion, without having
to muck with the entire contents everywhere a uses-stmt
for the grouping exists?

I just want to write

   uses SshProtocolVersion {
      mandatory false;
    }

or maybe:

   uses SshProtocolVersion {
     mandatory true;
   }

and let the compiler do all the low-level revisions.

One of the biggest complaints I got from SNMP NMS developers
during all the years I wrote agent code was that SNMP
had no reuse.  No 2 MIBs seem to do the same similar
thing in the same way.  At every level, all the way
down to how an address or a protocol version is specified.
Every MIB was a 'hard-craft or nothing' kind of project.
Just like CLI.

I was hoping YANG could do better than that.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Fri, 25 Jul 2008 18:59:13 -0400

>name collision protection, so they are much more bullet-proof

When I say "meaningful" I mean the appearance of the node
in a configuration conveys a specific meaning.  In my example,
the "ssh" node turns on the ssh server.

When I say "meaningless", I mean the appearance of the node
in a configuration conveys no meaning.  In my example, the
"services" no has no meaning of its own.  It serves as a
container to hold the "services" offer by the system.

Use of this term is not meant to bequeath or demolish
the inherent nobility of nodes of any class, color, or
modeling language.

>   uses SshProtocolVersion {

What does it mean to make the "use" of a grouping mandatory?
Is every node in that grouping now mandatory?  Are you seeing
this as a serious modeling need?

Even if "protocol-version" were the only thing inside the grouping
SshProtocolVersion, what would marking it mandatory mean?
"protocol-version" has two child nodes, neither of which is mandatory.
This means I now have to create the <protocol-version> node, even
though it has no intrinsic meaning.  This means that a device has
to throw an error if the application fails to create a node that
both the client and the server agree has no intrinsic value.  Is
that what you are wanting?

>I was hoping YANG could do better than that.

This was not a technology problem.  YANG will not stop 60 cooks
from making 60 recipes for spaghetti sauce.  My experience is that
backbone, hard work, and endless meetings are the only say to
convince people that their sauce is not sufficiently different from
the standard sauce to cover the cost of making it, bottling it, and
selling it.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 16:41:18 -0700

> this as a serious modeling need?

What I really need to make the abstraction in the data model
match the conceptual data model is a complex data type,
but I'm willing to try the grouping approach instead.

In this example, I may want different properties for
different usages:

   container ssh-client {
       uses SshProtocolVersion {
           mandatory false;
           description
              "If missing, then the SSH client software will
               use any SSH protocol version.  If present, then
               only the specified protocol versions will be used.";
       }
       // more fields here...
   }

   container ssh-server {
       uses SshProtocolVersion {
         mandatory true;
         description
            "The SSH server will only use the specified protocol versions.";
       }
       // more fields here...
   }

In a data model for monitoring, I may want to
report an SSH protocol version, and might want a non-config version:

   container host-ssh-versions {
       uses SshProtocolVersion {
          config false;
       }
   }

Andy

---

From: Andy Bierman <[email-masked]>
Date: Fri, 25 Jul 2008 19:08:59 -0700

> Phil Shafer wrote:

It's just a coincidence, but this example
works much better when it is defined with bits:

    typedef SshProtocolVersion {
       description "Define versions of the SSH protocol are allowed";
       type bits {
          bit v1 {
             description "Allow SSH V1";
          }
          bit v2 {
             description "Allow SSH V2";
          }
       }
     }

     leaf ssh-client {
        type SshProtocolVersion;
        mandatory false;
     }

     leaf ssh-server {
        type SshProtocolVersion;
        mandatory true;
     }

This same sort of reuse should be possible for
containers and not just the special subtree called bits.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Sat, 26 Jul 2008 01:50:10 -0400

>containers and not just the special subtree called bits.

This sort of reuse is possible for containers using refinements.
The issue is that currently you are required to refine the nodes
you want to change, where you want to mark the use as mandatory and
let the solution magically work it out.

You don't want visibility into the grouping, but something has to
decide _why_ the container is mandatory.  I don't think we have
enough magic to make it work out.

I also dislike the idea of giving an error when a config doesn't
contain a node that has no meaning and no children.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Sat, 26 Jul 2008 10:34:13 -0700

> let the solution magically work it out.

No more magic than the rest of the work
a YANG compiler needs to do.

All your examples seem to be inline, which is how CLI and MIBs
are defined as well.  NETCONF exists because the programmatic
interface provided by CLI and/or SMIv2 based data models
have not worked very well for standards-based configuration.

We should examine the reasons for that problem, as we
tweak a clause here and there.  I completely understand
why DaveH wants to get everybody looking at the same
picture on the same page.  We cannot possibly agree
on the language tweaks without agreeing on the big picture.

> enough magic to make it work out.

If the grouping represents an abstract construct,
then it is easy to decide how that abstraction is
being used in any given context.  I do this everyday
with C pointers, eg., 'const', 'static', 'volatile'.

The draft says mandatory has no effect for a set of sibling nodes
unless their parent is present.  This is correct, and it should
work this way for all nodes, and it does, except
for NP containers.

So my workaround is to always use the presence-stmt. E.g.,

   grouping Name {
     container name {
       presence "If present, then the parent entity has a name.";

       // 3 - 5 leafs breaking out all the name field components
       // 2 mandatory, and 3 not mandatory
     }
   }

If I want an optional name, then I can create a new grouping:

   grouping OptName {
     uses Name {
       container name {
          leaf first {
             mandatory false;
          }
          leaf last {
             mandatory false;
          }
       }
     }
   }

This is OK I guess.  I still think we will want a more
powerful (less verbose) syntax in the end to override
a property for an entire subtree, but this brute force
method can be done just once in a new grouping, so
it's not so bad.  And yes, the DM modeler for
some piece of code will need to know the exact differences
between Name and OptName, but not everybody will care.

> contain a node that has no meaning and no children.

Do you just want to outlaw NP containers all together?
All containers would be presence containers?
I don't really think they are worth worrying about.
An empty NP container amounts to garbage-in/garbage out in the end,
and if the agent wants to prune it (since is has no impact
on the config) then it should do that.  Otherwise, it is
just wasting a little memory, and not really a problem.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Sat, 26 Jul 2008 11:41:01 -0700

Hi,

> If I want an optional name, then I can create a new grouping:

I don't really need OptName, right?
It would only be useful if I had a use for <name/>,
and to properly refine a presence container like this,
I would have to define what it means to have
just an empty <name/> element in the config.
(E.g., use the site-specific default instead.)

This is reasonable.  I still don't think it is
worth a separate description clause.  Multiple
description clauses will lead to multiple CLRs to decide
what kind of text goes in each one.  I would rather
have 1 description clause with zero CLRs.

The presence-stmt is still not a great model for
an encapsulation container.  In this example, I want
either a valid <name> subtree or no <name> element
at all.  I think the rules for presence container
give me that, as long as at least one child node
is mandatory.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 26 Jul 2008 20:52:12 +0200 (CEST)

Hi,

> I don't really need OptName, right?

No, I was just going to suggest that.

> In this example, I want

Yes.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 26 Jul 2008 12:05:43 -0700

>> give me that, as long as at least one child node

I like your idea of changing the presence-stmt argument
from a string to a boolean.

It may not be clear to people why conceptualizing this
particular portion of the XML tree in this manner is
a feature.

The rules for mandatory within a 'choice' subtree are still
a little unclear to me, for example.  If I have mandatory false
on the choice, and there are mandatory leafs within at least
one case, does that make the choice mandatory anyway?
I hope not.  The mandatory property should just mean
"if you use this case arm, this leaf is mandatory".

The draft should explain the upward ripple on NP containers
better, and why it works this way.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 26 Jul 2008 21:14:14 +0200 (CEST)

> from a string to a boolean.

This (could) allow you to turn off presence in 'uses', but I'm not
sure that would be a feature...

> one case, does that make the choice mandatory anyway?

No.  I agree that the spec is not very clear on this, and that we
should fix this.

> "if you use this case arm, this leaf is mandatory".

Right.

> better, and why it works this way.

Ok.  But how much of the "why" questions should really be answered in
the spec?  Should we discuss rejected design alternatives (I hope
not).

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 26 Jul 2008 12:35:31 -0700

> sure that would be a feature...

A P container with mandatory fields is not mandatory itself.
Setting presence to false would be the only way to for an
implementation to say "this container must be present
in a valid config" instead of "if it is present, it
must have all the mandatory fields."  The implementation may
not support the semantics for the empty container either.
What then?  Can it refine a P container?

> the spec?  Should we discuss rejected design alternatives (I hope

No -- just the accepted design.
That's enough work. :-)

Andy