Subject: [netmod] mandatory-stmt

From: Andy Bierman <[email-masked]>
Date: Wed, 14 May 2008 10:45:04 -0700

Hi,

I think the application of the 'mandatory-stmt' should
be more consistent throughout the language.

It is allowed within:
   - leaf
   - choice
   - anyxml

It is not allowed within:
   - container
   - leaf-list
   - list
   - case

I realize that container has 'presence' and leaf-list/list have
the 'min-elements' clauses instead.

IMO, a case-stmt should allow mandatory-stmt to be present.
This is just an omission.  The use case is simply to
reduce the duplication.

  choice foo {
    mandatory false;
    case A {
      mandatory true;
      // same as if 'mandatory true;' was present in
      // every node in the A case-arm
    }
  }

A container should also allow the mandatory-stmt.
This is different than the presence-stmt, which only provides
a description of what it means *if* the container is present.

For consistency, the mandatory-stmt should be allowed in leaf-list
and list, but must be consistent with 'min-elements' if also present:

    mandatory true;   -->   min-elements 1;
    mandatory false;  -->   min-elements 0;   // default

Andy

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

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 14 May 2008 21:20:48 +0200 (CEST)

Hi,

> be more consistent throughout the language.

[...]

>       // every node in the A case-arm

I would argue that the meaning of 'mandatory true' in your proposal
above is inconsistent with the other applications of 'mandatory' we
have.  In your proposal it affects not the current node but child
nodes.

Can I override this in individual nodes in the case branch:

  case A {
     mandatory true;
     leaf foo {
       mandatory false;
     }
  }

> a description of what it means *if* the container is present.

We had long discussions in the design team about this.  What does it
mean that a container is mandatory?  That it MUST be present in the
config?  If the container is always there it does not carry any
semantic meaning.  We do this with "non-presence" containers today.

Do you suggest that if mandatory is true on a container, then the
presence statement MUST NOT be there, and vice versa?

Or do you suggest that mandatory true works like in the case statement
above?

>     mandatory false;  -->   min-elements 0;   // default

I don't agree that it's more consistent to use a statement in places
where it doesn't add any value.  Or do you think it adds value?

/martin

---

From: Andy Bierman <[email-masked]>
Date: Wed, 14 May 2008 14:21:22 -0700

> have.  In your proposal it affects not the current node but child

you are right.
I realized that after I sent the mail.
It should not be allowed for case-stmt.

> semantic meaning.  We do this with "non-presence" containers today.

It makes more sense for RPC <input>, <output>, and <notification>.
Mandatory true means the node must be present (in these cases),
even if it is an empty container.

> where it doesn't add any value.  Or do you think it adds value?

I think it is better to be lenient in what is entered by the user.
To me, 'mandatory true' or 'min-elements 1' are both equally valid,
and make sense.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 14 May 2008 17:32:47 -0400

>even if it is an empty container.

If it's empty and not a presense container, then it carries
no useful information.  Why would it be mandatory?

>To me, 'mandatory true' or 'min-elements 1' are both equally valid,

Having both is an expense we don't need.  As a reader, I don't want
to have to look for both.  As a developer, I don't want to have to
check for both.  Why make an optimization for sloppy YANG writers?

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 14 May 2008 15:42:09 -0700

> no useful information.  Why would it be mandatory?

IMO, that is up to the data model write.
Maybe there is a choice within the container or other
constructs that end up with no instances, so the
the data model can convey an empty set in an extensible manner.

   rpc do-search {
    input {
      leaf search-type {
        type string;
        mandatory true;
      }
      leaf search-string {
        type string;
        mandatory true;
      }
    }
    output {
       container search-matches {
         mandatory true;
         choice search-type {
           ...
         }
       }
    }

    <rpc-reply message-id="101">
      <data>
        <search-matches/>
      </data>
    </rpc-reply>

It is just as valid to give the manager a stable 'search-matches'
node in the reply as to leave it out.

> check for both.  Why make an optimization for sloppy YANG writers?

One could consider the special-case nature of all the various
YANG object types to be an expense we don't need.

Most DML features are very subjective in nature.
It doesn't really help to characterize mechanisms you don't like
as 'noise' or 'sloppy'.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Thu, 15 May 2008 10:16:56 -0700

Phil Shafer wrote:
> No, if it doesn't make sense, it's up to us to forbid it
> and avoid the confusion of meaningless YANG (and content).
> 

IMO, the concept of mandatory true/false is useful and
simple to understand.  I do not agree it is meaningless.
I prefer this simple clause to 'must' and 'presence' and 'min-elements'.
I don't really care that much, though.  (I already have a YANG cheat sheet
to remind of of all the little quirks and details -- it's almost
as bad as XSD in that regard ;-)

> If it's just as valid to leave it out, why would you want to make
> it mandatory?
> 
> Sorry, but you are trying to give the writer two choices, one
> that context sensitive and one that's not so meaningful but
> less context dependent.  I don't see why we'd allow the writer
> this choice, given that readers and clarity are more important
> that a writer that wants to be context insensitive.  Why would
> the writer need or want this choice?
> 
> Yes, design work is subjective and there are many right answers,
> but there are also many wrong ones.  Consider:
> 
> http://www.8sharp.com/inspired/images/norman_book.jpg
> http://snarfd.com/wp-content/uploads/2007/11/sorapot_white.jpg
> 
> Language design is subjective, but every feature needs a semi-objective
> cost/benefit analysis to see if it's worth inclusion in the language.
> Here I see the cost but don't see the benefit.  I have a hard time
> with The idea of helping writers that want to say "mandatory true"
> instead of "min-elements 1" because they don't want to think about
> if they are inside a list or not.

I think it matters more to the readers than the writer of the module.

I will let this thread go.  I think some other WG members
(besides the YANG co-authors) should get involved and express
their opinions.  (If not, then why didn't we just publish YANG
as Experimental a year ago?)

Andy

---

From: Phil Shafer <[email-masked]>
Date: Thu, 15 May 2008 13:25:33 -0400

>simple to understand.  I do not agree it is meaningless.

My point was that an empty XML element that doesn't have a meaning
is meaningless, making it mandatory would be unnecessary.  If it
doesn't mean anything, I shouldn't have to emit it.

Thanks,
 Phil

---

From: Phil Shafer <[email-masked]>
Date: Thu, 15 May 2008 12:57:51 -0400

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 15 May 2008 20:34:10 +0200 (CEST)

>        container search-matches {

This usage of mandatory true on a container seems quite arbitrary to
me.  I think you agreed that it doesn't add any extra information to
the data model.  So when a data model designer is writing his
container, how will he determine whether to use 'mandatory true' or
not?  It is also different from our other constructs b/c it controls
the XML encoding only.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 15 May 2008 12:05:01 -0700

> not?  It is also different from our other constructs b/c it controls

It is not XML encoding only.
It should be up to the DM writer if they want
a placeholder node or not.  E.g:

   container interfaces {
     mandatory true;
     must ".";
     presence
       "Root of all interface information.
        Presence indicates the device has some interface information.";

     leaf ifNumber {
        type uint32;
        mandatory true;
        config false;
     }

     leaf ifLastChangeTime {
        type yang:date-and-time;
        config false;
     }

     list interface {
       key name;
       min-elements 0;
       mandatory false;
       ...
     }
   }

Why bother creating an /interfaces root for the interface info?
IMO, it is useful for creating a stable API.  I can configure
access control for /interfaces and not worry if new child nodes
were added underneath.  Same applies for applications or operators
hard-wiring or hand-coding filters.

What if I want all implementations to have an interfaces root,
to make sure filters or ACEs for '/interfaces' are clear and
unambiguous and static?  What if an agent MUST at least
return 'ifNumber==0' to be compliant to the Acme Interface module?
Is that meaningless?  Just leaving out nodes instead can
be masked by access control.

IMO, 'mandatory true' is more intuitive than 'must "."'.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 15 May 2008 21:38:21 +0200 (CEST)

Hi,

> a placeholder node or not.  E.g:

Absolutely.  These kind of placeholder nodes are very useful.  But
there's no need for 'mandatory true' on them.  Just use an ordinary
("non-presence") container.

>         Presence indicates the device has some interface information.";

So this says that if the node is present, then the device has some
interface information.  But it is also mandatory, so it has to be
present!  This does not make much sense to me.

Also, the 'must "."' expression doesn't make any sense.  must
expressions are evaluated for data nodes that exist in the tree.  So
this expression says "if /interfaces exists, then it must exist".

> hard-wiring or hand-coding filters.

Sure.

> What if I want all implementations to have an interfaces root,

Make it an ordinary container.

> return 'ifNumber==0' to be compliant to the Acme Interface module?

In this case you have nothing to worry about at all - if there's a
mandatory leaf under an ordinary container, then you know that the
container will always be sent in the XML.

> IMO, 'mandatory true' is more intuitive than 'must "."'.

They are different things, as explained above.

>        config false;

mandatory true in combination with config false doesn't make sense.
mandatory means that the node must exist in a valid configuration.
Thus it does not apply to non-config nodes.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Wed, 21 May 2008 08:09:16 -0700

Martin Bjorklund wrote:
> ....

> Thus it does not apply to non-config nodes.

Then the draft needs to be clarified or corrected, because
the mandatory-stmt is allowed for leafs within notifications
and RPC input/output.  If it has no meaning in these cases,
then the draft needs to specify what happens if they are present.
(Same applies for config-stmt.)

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 21 May 2008 20:24:39 +0200 (CEST)

> (Same applies for config-stmt.)

The idea was that mandatory does make sense in e.g. RPC input
parameters.  The draft currently says this for input (and similar for
output and notifications):

  If a leaf in the input tree has a "mandatory" statement with the
  value "true", the leaf MUST be present in a NETCONF RPC invocation.

I think we need some clarifications to this.  As it stands right now,
the only case that is not covered is non-config nodes.  If we don't
want to allow mandatory on non-config nodes, this should be spelled
out explicitly.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Wed, 21 May 2008 11:38:22 -0700

> want to allow mandatory on non-config nodes, this should be spelled

Yes -- you spelled it out at the last IETF I think:

   config-stmt has no meaning (ignored or compiler warning):
    - /some-rpc/input/*
    - /some-rpc/output/*
    - /some-notification/*

   for mandatory-stmt:
     - /some-rpc/input/*      : must be present in the input parameters
     - /some-rpc/output/*     : must be present in the output if no errors
     - /some-notification/*   : must be present in the notification

Andy