Re: [Netconf] [yang-doctors] YANG Doctor question: empty mandatory choice?

[Martin Bjorklund <[e-mail]>]

Robert Wilton <rwilton=[e-mail]> wrote:
> 
> 
> On 01/08/2018 17:09, Andy Bierman wrote:
> >
> >
> > On Wed, Aug 1, 2018 at 9:01 AM, Robert Wilton <[e-mail]
> > <mailto:[e-mail]>> wrote:
> >
> >
> >
> >     On 31/07/2018 21:31, Andy Bierman wrote:
> >>
> >>
> >>     On Tue, Jul 31, 2018 at 12:39 PM, Eric Voit (evoit)
> >>     <[e-mail] <mailto:[e-mail]>> wrote:
> >>
> >>         > From: Juergen Schoenwaelder, July 31, 2018 1:48 PM
> >>         >
> >>         > On Mon, Jul 30, 2018 at 08:41:42PM +0200, Martin Bjorklund
> >>         wrote:
> >>         > >
> >>         > > The empty mandatory choice does provide value since it
> >>         requires that
> >>         > > some transport-specific parameters are configured. 
> >>         However, can we
> >>         > > assume that all transports require configuration
> >>         parameters here?
> >>         >
> >>         > Can you have a receiver without any transport parameters?
> >>         >
> >>         > > It is probably safest to not have a mandatory choice, and
> >>         instead
> >>         > > ensure that each transport augements the proper params --
> >>         and since
> >>         > > this is YANG 1.1, the transport params that are augmented
> >>         can actually
> >>         > > be marked as mandatory.
> >>         >
> >>         > Frankly, an empty mandatory choice quite clearly says "this
> >>         is incomplete and
> >>         > unusable without an augmentation".
> >>
> >>         My read above is the YANG doctor's position is that we should
> >>         *not* use the empty mandatory choice.  Let me know if I got
> >>         this wrong.
> >>
> >>
> >>     I do not think a consensus call has been done yet, but I agree
> >>     with Juergen
> >>     and already raised the point that YANG conformance does not handle a
> >>     "MUST augment" use-case very well.
> >     I think that "empty choice + mandatory true" it is OK from a
> >     conformance perspective.  The concept seems similar to an
> >     programmatic interface, abstract class, or even the abstract
> >     identity idea that has been proposed for YANG.  If a server
> >     implements the module but no augments of the choice then it cannot
> >     be configured because the constraint will always fail.  Andy, is
> >     your concern that tooling will warn that part of the model is
> >     unusable?
> >
> >
> > That is possible.
> > I agree with Juergen that a mandatory empty choice clearly indicates
> > that the module is incomplete
> > and unusable on its own.  Is that a feature?
> Yes, making that indication is the whole purpose of adding the
> "mandatory: true" to the empty choice.  Note, that I see that the
> "mandatory true" is there to say that every configured subscription
> must have a transport configured, which if true, doesn't seem
> unreasonable.

Note that the model already has a 'transport' leaf that is mandatory.

The choice is an explicit placeholder for transport-specific
additional parameters.

This proposed design is slightly different than the design in
ietf-interfaces; in interfaces we have:

   leaf type { ... }
   // type-specific augmentations here

For example (from the RFC):

   augment "/if:interfaces/if:interface" {
     when "if:type = 'ianaift:ethernetCsmacd'";

     container ethernet {
       leaf duplex {
         ...
       }
     }
   }


In the notif model the proposal is:

  leaf transport { ... }

  ...
    choice transport-specific-params {
      // transport-specific augmentations here
    }


Note that if the choice is not marked as mandatory, the resulting
model will be less strict / useful compared to using a design like in
the interfaces model (w/o the choice).  To demonstrate, suppose we
have a transport 'example-udp' that needs a mandatory 'address' and an
optional 'port'.  With the choice we'd have:

  augment '/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver'
        + '/sn:transport-specific-params' {
    when 'derived-from(../../../../transport, "ex:example-udp")';

    case example-udp-params {
      leaf address {
        mandatory true;
        ...
      }
      leaf port {
        ...
      }
    }
  }
  
If the choice is not mandatory, the model would allow a client to
configure the transport leaf to 'example-udp', but not configure an
address.


Without the choice, we'd do:

  augment '/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver'
    when 'derived-from(../../../transport, "ex:example-udp")';

    leaf address {
      mandatory true;
      ...
    }
    leaf port {
      ...
    }
  }
  

In this case, or if the choice is mandatory, the model would require
the client to configure an address if the transport is 'example-udp',
which is what we want.


But if the choice is marked as mandatory, *all* transports MUST define
some transport-specific parameters, even if that is not needed
(unclear if this will ever happen...)


Thus, I prefer Eric's original model w/o the choice.  The choice is
supposed to be clever, but might end up being confusing, and I don't
think it adds any value anyway.




/martin

> I.e. my main point is that I don't have an issue with
> this generic YANG design.
> 
> In this particular instance, I'm also fine if "mandatory: true" is
> left out, but I don't really agree with writing the equivalent of
> "mandatory: true" in the description, that seems like a poor
> compromise.
> 
> However, this is probably all bike-shedding.  I think that any of the
> discussed solutions is acceptable, as long as it is obvious to the
> readers of the YANG modules that a case statement must be provided for
> it to be useful, and I make the assumption that sane vendors won't
> enable the "configured" feature, if there is no actual way of
> configuring usable subscriptions.
> 
> Perhaps Eric can propose his preferred choice, and we can see if
> anyone still objects, otherwise maybe we can move on?
> 
> Thanks,
> Rob
> 
> 
> >
> > Andy
> >
> >
> >     I have to say that much prefer the option of putting "mandatory:
> >     true" in the choice than "MUST provide an implementation" in the
> >     description because the former is machine readable whilst the
> >     latter is not.
> >
> >     However, I would also be fine not to have the "mandatory: true",
> >     but with the choice description to state something along the lines
> >     that the empty choice is to allow for augmentations of different
> >     transports, and configured subscriptions may not be usable unless
> >     at least one transport case statement is available."  But perhaps
> >     some implementation will provide the flexibility of defining a
> >     single transport for all subscriptions (if this is feasible).
> >
> >     One other observation that could affect the decision here is that
> >     YANG allows "mandatory: true" to be removed in a future revision
> >     in a backwards compatible way, but doesn't allow it to be added.
> >
> >     Thanks,
> >     Rob
> >
> >
> >>
> >>     I prefer the MUST be in the description-stmt for the choice,
> >>     instead of "mandatory true". (I prefer SHOULD but if the WG wants
> >>     MUST)
> >>
> >>
> >>     Andy
> >>
> >>
> >>
> >>         That would mean that each transport document supporting
> >>         configured subscriptions would then augment transport
> >>         specific parameters to
> >>         "/subscriptions/subscription/receivers/receiver".  And
> >>         (assuming the "single transport" decision of IETF100 isn't
> >>         changed), that the identity "transport" could be leveraged to
> >>         enforce that only a single transport specific set of
> >>         credentials are associated with a receiver.
> >>
> >>         A sample YANG augmentation for NETCONF would then look like:
> >>
> >>         module ietf-netconf-subscribed-notifications {
> >>
> >>           prefix nsn;
> >>
> >>           import ietf-netconf-client { prefix ncc; }
> >>           import ietf-subscribed-notifications { prefix sn; }
> >>
> >>           identity netconf {
> >>             base sn:transport;
> >>             base sn:inline-address;
> >>             description
> >>               "NETCONF is used as a transport for notification
> >>         messages and
> >>                state change notifications.";
> >>           }
> >>
> >>           augment
> >>         "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" {
> >>            when 'derived-from(../../../transport, "nsn:netconf")';
> >>            description
> >>               "This augmentation allows NETCONF specific parameters
> >>         to be
> >>               exposed for a receiver.";
> >>             leaf netconf-endpoint {
> >>               type leafref {
> >>                 path
> >>         "/ncc:netconf-client/ncc:initiate/ncc:netconf-server" +
> >>                         "/ncc:endpoints/ncc:endpoint/ncc:name";
> >>               }
> >>               mandatory true;
> >>               description
> >>                 "Remote client which need to initiate the NETCONF
> >>         transport if
> >>                 an existing NETCONF session from that client is not
> >>         available.";
> >>             }
> >>           }
> >>         }
> >>
> >>         Which results in:
> >>           +--rw subscriptions
> >>              +--rw subscription*
> >>                 +--rw transport         transport {configured}?
> >>                 +--rw receivers
> >>                    +--rw receiver*
> >>                       +--rw nsn:netconf-endpoint leafref
> >>
> >>         Eric
> >>
> >>
> >>         > /js
> >>         >         > --
> >>         > Juergen Schoenwaelder  Jacobs University Bremen gGmbH
> >>         > Phone: [phone]  Campus Ring 1 | 28759 Bremen | Germany
> >>         > Fax:   [phone]       
> >>          <https://www.jacobs-university.de/
> >>         <https://www.jacobs-university.de/>>
> >>
> >>
> >>
> >>
> >>     _______________________________________________
> >>     yang-doctors mailing list
> >>     [e-mail] <mailto:[e-mail]>
> >>     https://www.ietf.org/mailman/listinfo/yang-doctors
> >>     <https://www.ietf.org/mailman/listinfo/yang-doctors>
> >
> >
>