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

Martin Bjorklund <mbj@tail-f.com> Sun, 05 August 2018 09:11 UTC

Return-Path: <mbj@tail-f.com>
X-Original-To: netconf@ietfa.amsl.com
Delivered-To: netconf@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 04331127AC2; Sun, 5 Aug 2018 02:11:31 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=unavailable autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id zgEYsFg9trPb; Sun, 5 Aug 2018 02:11:29 -0700 (PDT)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 1C9ED12785F; Sun, 5 Aug 2018 02:11:29 -0700 (PDT)
Received: from localhost (h-80-27.A165.priv.bahnhof.se [212.85.80.27]) by mail.tail-f.com (Postfix) with ESMTPSA id B87A71AE0144; Sun, 5 Aug 2018 11:11:23 +0200 (CEST)
Date: Sun, 05 Aug 2018 11:11:23 +0200 (CEST)
Message-Id: <20180805.111123.2123994471181114333.mbj@tail-f.com>
To: rwilton=40cisco.com@dmarc.ietf.org
Cc: andy@yumaworks.com, evoit@cisco.com, yang-doctors@ietf.org, netconf@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <958669b9-c523-3c43-eca4-fbc255fc1bc8@cisco.com>
References: <05ee68cd-ccc0-6803-6c71-b3952ee5608d@cisco.com> <CABCOCHRtg9jB0=b5bPPT3MS0QJcwgAY24Fg0RewXhPMR8Y+O0w@mail.gmail.com> <958669b9-c523-3c43-eca4-fbc255fc1bc8@cisco.com>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://mailarchive.ietf.org/arch/msg/netconf/XMntOWNPIinAsDgbipARluK5klQ>
Subject: Re: [Netconf] [yang-doctors] YANG Doctor question: empty mandatory choice?
X-BeenThere: netconf@ietf.org
X-Mailman-Version: 2.1.27
Precedence: list
List-Id: Network Configuration WG mailing list <netconf.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netconf>, <mailto:netconf-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netconf/>
List-Post: <mailto:netconf@ietf.org>
List-Help: <mailto:netconf-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netconf>, <mailto:netconf-request@ietf.org?subject=subscribe>
X-List-Received-Date: Sun, 05 Aug 2018 09:11:31 -0000

Robert Wilton <rwilton=40cisco.com@dmarc.ietf.org> wrote:
> 
> 
> On 01/08/2018 17:09, Andy Bierman wrote:
> >
> >
> > On Wed, Aug 1, 2018 at 9:01 AM, Robert Wilton <rwilton@cisco.com
> > <mailto:rwilton@cisco.com>> wrote:
> >
> >
> >
> >     On 31/07/2018 21:31, Andy Bierman wrote:
> >>
> >>
> >>     On Tue, Jul 31, 2018 at 12:39 PM, Eric Voit (evoit)
> >>     <evoit@cisco.com <mailto:evoit@cisco.com>> 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: +49 421 200 3587  Campus Ring 1 | 28759 Bremen | Germany
> >>         > Fax:   +49 421 200 3103       
> >>          <https://www.jacobs-university.de/
> >>         <https://www.jacobs-university.de/>>
> >>
> >>
> >>
> >>
> >>     _______________________________________________
> >>     yang-doctors mailing list
> >>     yang-doctors@ietf.org <mailto:yang-doctors@ietf.org>
> >>     https://www.ietf.org/mailman/listinfo/yang-doctors
> >>     <https://www.ietf.org/mailman/listinfo/yang-doctors>
> >
> >
>