Subject: Re: [netmod] Text in import to indicate whether a module is needed as import-only or as implemented

From: Benoit Claise <[email-masked]>
Date: Mon, 2 Mar 2020 17:57:37 +0100

Sorry to resurrect this old email thread.
To me, it's an important piece of information to know that 
ietf-netconf-acm is optional to implement.

It seems that we have 3 potential places where to insert this information
1. The associated document. We could and should insert it into the RFC text.
     Drawback: Somehow the YANG module is looked at independently of the 
associated document
2. import-stmt: people on the list apparently don't like this
3. module description? What harm would it do if the description could 
contain this info?

Regards, Benoit
>
>
> On Wed, Jan 8, 2020 at 5:44 AM Ladislav Lhotka <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     On Wed, 2020-01-08 at 04:49 -0800, Andy Bierman wrote:
>     >
>     > On Wed, Jan 8, 2020 at 1:11 AM Ladislav Lhotka <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     > > On Tue, 2020-01-07 at 14:29 +0000, Balázs Lengyel wrote:
>     > > > If that is the consensus, I can remove the description
>     statements, no big
>     > > > deal. (I actually like the statements, but they are not
>     important for this
>     > > > draft)
>     > >
>     > > Of course, it is not that important, but I don't see how this
>     information
>     > > could
>     > > be harmful, if it is included with the import. In my view, it
>     is not meant
>     > > as a
>     > > conformance requirement but just an info from the module
>     author about the
>     > > meaning of the import statement.
>     > >
>     >
>     > It adds a lot of extra work but more importantly the import-stmt
>     is the wrong
>     > place
>
>     What work do you mean? I thought that it would be just info for
>     potential
>     developers (or their managers) that implementing the module requires
>     implementing other modules and functionality - or not.
>
>
>
> It is duplication because the individual data-def statements should 
> have any notes
> about implementation requirements. The duplication may even be wrong.
> E.g., in the module it says NACM is not required, but what if some objects
> have NACM requirements listed in the Security Considerations section?
> That is the RFC section to discuss NACM requirements.
>
>
>     For example, if a module imports ietf-netconf-nacm only for using
>     "node-
>     instance-identifier" type, it is relatively uninteresting. Otherwise,
>     implementation of the module may just be out of question.
>
>
>     > to document such a complex and unrelated issue as server conformance
>     > requirements.
>     >
>     >
>     > > The root of this problem (and design flaw of YANG, IMO) is
>     that import is
>     > > "overloaded" with two different purposes, one of which
>     effectively requires
>     > > that
>     > > the imported module be also implemented, while the other doesn't.
>     > >
>     >
>     > The import-stmt is only used to map a local prefix to an
>     external module.
>
>     But one thing is using a prefix for accessing top-level types and
>     groupings
>     (i.e. stuff in YANG modules), and another thing is accessing
>     schema nodes, which
>     have to be present in the schema tree. In complicated data models,
>     it is not
>     exactly easy to figure out all these dependencies.
>
>
> I do not agree these are different things.
> In both cases the prefix is used to determine the imported module that 
> contains the identifier.
>
>
>     So maybe what is really overloaded are the namespace prefixes:
>     they are used for
>     addressing YANG modules, schema nodes and instances (in XPath).
>
>     Lada
>
>
>
> Andy
>
>
>     > This proposal to add conformance info the the import-stmt would
>     overload it
>     > with
>     > another purpose.
>     >
>     > Not even a typedef is easy to classify  (e.g., leafref requires
>     implementation
>     > of a data node).
>     > I certainly agree that YANG conformance is poorly specified, poorly
>     > understood, and
>     > in real need of improvement. Likewise, the import-stmt is also
>     in need of some
>     > improvement
>     > since import-by-exact-revision is (and has always been) poorly
>     designed.
>     >
>     >
>     > > Lada
>     > >
>     > > > Balazs
>     >
>     > Andy
>     >
>     >
>     > > > -----Original Message-----
>     > > > From: Martin Bjorklund <[email-masked] <mailto:[email-masked]>>
>     > > > Sent: Tuesday, January 7, 2020 2:38 PM
>     > > > To: Balázs Lengyel <[email-masked]
>     <mailto:[email-masked]>>
>     > > > Cc: [email-masked] <mailto:[email-masked]>;
>     [email-masked] <mailto:[email-masked]>; [email-masked]
>     <mailto:[email-masked]>
>     > > > Subject: Re: [netmod] Text in import to indicate whether a
>     module is
>     > > needed as
>     > > > import-only or as implemented
>     > > >
>     > > > Hi
>     > > >
>     > > > I agree w/ Andy and others that we should not add this to
>     the import's
>     > > > description.  I don't think this kind of conformance text
>     belongs to the
>     > > > import's description.  If you think it is important to state
>     this, the
>     > > best
>     > > > place is probably as plain text in the document itself.
>     > > >
>     > > >
>     > > >
>     > > > /martin
>     > > >
>     > > >
>     > > > Balázs Lengyel <balazs.lengyel=[email-masked]
>     <mailto:[email-masked]>> wrote:
>     > > > > As a draft author who was asked to add text about the
>     imports IMHO
>     > > > >
>     > > > > *   it would be easy for me to remove the description from
>     the import.
>     > > > > Actually I really just want to know what is acceptable to
>     the group, so
>     > > I
>     > > > > can proceed
>     > > > > *   I also think that adding this text is in most cases
>     easy and it does
>     > > not
>     > > > > need updates later.
>     > > > > *   The rules in some cases might not be trivial.
>     > > > >
>     > > > > *   Imported YAMs need to be implemented if
>     > > > >
>     > > > > *   Imported parts are included in Xpath (augment, when,
>     must, require-
>     > > > > instance)
>     > > > >
>     > > > > *   Imported YAMs do not need to be implemented if only
>     the following
>     > > are
>     > > > > used
>     > > > >
>     > > > > *   Types
>     > > > > *   Features
>     > > > > *   extensions
>     > > > >
>     > > > > *   Ambiguous if
>     > > > >
>     > > > > *   groupings are used
>     > > > > *   if the dependency is not formally defined by YANG, but
>     functionally
>     > > > > needed. (E.g. notification-capabilities does not formally
>     need YANG-
>     > > > > Push
>     > > to
>     > > > > be implemented, however there is no sense in defining
>     capabilities if
>     > > YANG-
>     > > > > Push is itself not implemented.)
>     > > > > *   deviation ?
>     > > > > *   other cases ?
>     > > > >
>     > > > > Regards Balazs
>     > > > >
>     > > > >
>     > > > >
>     > > > > From: netmod <[email-masked]
>     <mailto:[email-masked]>> On Behalf Of Andy Bierman
>     > > > > Sent: 2019. december 19., csütörtök 17:23
>     > > > > To: Ladislav Lhotka <[email-masked] <mailto:[email-masked]>>
>     > > > > Cc: NetMod WG <[email-masked] <mailto:[email-masked]>>
>     > > > > Subject: Re: [netmod] Text in import to indicate whether a
>     module is
>     > > > > needed as import-only or as implemented
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > > On Thu, Dec 19, 2019 at 8:00 AM Ladislav Lhotka
>     <[email-masked] <mailto:[email-masked]> <mailto:
>     > > > > [email-masked] <mailto:[email-masked]>> > wrote:
>     > > > >
>     > > > > On Thu, 2019-12-19 at 07:52 +0000, Schönwälder, Jürgen wrote:
>     > > > > > On Thu, Dec 19, 2019 at 08:23:27AM +0100, Ladislav
>     Lhotka wrote:
>     > > > > > > I don't see how YANG syntax defines this. If a module
>     imports
>     > > > > > > ietf-netconf- acm, it could be because
>     > > > > > >
>     > > > > > > - it just uses a typedef, such as
>     "node-instance-identifier", and
>     > > then
>     > > > > > >   ietf-netconf-acm needn't be implemented (but can be),
>     > > > > > >
>     > > > > > > or
>     > > > > > >
>     > > > > > > - it augments ietf-netconf-acm, which makes sense only
>     if the latter
>     > > > > > >   module is implemented.
>     > > > > > >
>     > > > > > > It it the YANG library that specifies whether a module is
>     > > > > > > implemented or not, but the "import" statement itself
>     doesn't tell
>     > > you
>     > > > > > > anything.
>     > > > > > >
>     > > > > >
>     > > > > > Can we not assume that an implementor will figure out
>     the difference?
>     > > > >
>     > > > > An implementor should be able to figure it out, but other
>     potential
>     > > > > module users may not. For example, if somebody is
>     evaluating whether
>     > > > > to use a module for their device or not, it is important
>     to know that
>     > > > > NACM has to be implemented (or not).
>     > > > >
>     > > > >
>     > > > >
>     > > > > You seem to be talking about a new conformance
>     documentation procedure
>     > > > >
>     > > > > that attempts to solve the problem "to use modules A, B,
>     and C
>     > > > > together
>     > > > >
>     > > > > to achieve some functionality X, all these conditions need
>     to be met"..
>     > > > >
>     > > > > (Sounds more like a problem for YANG Packages to solve)
>     > > > >
>     > > > >
>     > > > >
>     > > > > IMO this is a much harder problem than something that can
>     be solved
>     > > > >
>     > > > > with extra description-stmt text. The writer is likely to
>     get it wrong
>     > > > > or not
>     > > > >
>     > > > > keep it up to date, so a tool to analyze the file seems
>     like a better
>     > > > > solution.
>     > > > >
>     > > > >
>     > > > >
>     > > > > Lada
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > > Andy
>     > > > >
>     > > > >
>     > > > >
>     > > > >
>     > > > > > Or someone writes a pyang plugin to determine from the
>     schema tree
>     > > > > > the kind of imports there are (for a given set of features).
>     > > > > >
>     > > > > > /js
>     > > > > >
>     > > > > --
>     > > > > Ladislav Lhotka
>     > > > > Head, CZ.NIC Labs
>     > > > > PGP Key ID: 0xB8F92B08A9F76C67
>     > > > >
>     > > > > _______________________________________________
>     > > > > netmod mailing list
>     > > > > [email-masked] <mailto:[email-masked]>
>     <mailto:[email-masked] <mailto:[email-masked]>>
>     > > > > https://www.ietf.org/mailman/listinfo/netmod
>     > > > >
>     -- 
>     Ladislav Lhotka
>     Head, CZ.NIC Labs
>     PGP Key ID: 0xB8F92B08A9F76C67
>
>     _______________________________________________
>     netmod mailing list
>     [email-masked] <mailto:[email-masked]>
>     https://www.ietf.org/mailman/listinfo/netmod
>
>
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Andy Bierman <[email-masked]>
Date: Mon, 2 Mar 2020 09:52:33 -0800

On Mon, Mar 2, 2020 at 8:57 AM Benoit Claise <[email-masked]> wrote:

> To me, it's an important piece of information to know that ietf-netconf-acm
> is optional to implement.
>
IMO it makes more sense to summarize the imported modules that need to be
implemented
and not mention the ones that are not required.  The module
description-stmt is better
than each import. (YANG 1.1 allows the same module to be imported multiple
times).

Andy

>
>
> On Wed, Jan 8, 2020 at 5:44 AM Ladislav Lhotka <[email-masked]> wrote:
>
>> > On Wed, Jan 8, 2020 at 1:11 AM Ladislav Lhotka <[email-masked]> wrote:
>> > > > If that is the consensus, I can remove the description statements,
>> no big
>> > > > deal. (I actually like the statements, but they are not important
>> for this
>> > > > draft)
>> > >
>> > > be harmful, if it is included with the import. In my view, it is not
>> meant
>> > > as a
>> > > conformance requirement but just an info from the module author about
>> the
>> > It adds a lot of extra work but more importantly the import-stmt is the
>> wrong
>> > place
>>
>> What work do you mean? I thought that it would be just info for potential
> It is duplication because the individual data-def statements should have
> any notes
> For example, if a module imports ietf-netconf-nacm only for using "node-
>> > > The root of this problem (and design flaw of YANG, IMO) is that
>> import is
>> > > "overloaded" with two different purposes, one of which effectively
>> requires
>> > > that
>> > The import-stmt is only used to map a local prefix to an external
>> module.
>>
>> (i.e. stuff in YANG modules), and another thing is accessing schema
>> nodes, which
>> have to be present in the schema tree. In complicated data models, it is
>> not
> So maybe what is really overloaded are the namespace prefixes: they are
>> used for
>> > in real need of improvement. Likewise, the import-stmt is also in need
>> of some
>> > improvement
>> > since import-by-exact-revision is (and has always been) poorly designed.
>> >
>> >
>> > > Lada
>> > >
>> > > > Balazs
>> >
>> > Andy
>> >
>> >
>> > > > From: Martin Bjorklund <[email-masked]>
>> > > > To: Balázs Lengyel <[email-masked]>
>> > > > Cc: [email-masked]; [email-masked]; [email-masked]
>> > > > Subject: Re: [netmod] Text in import to indicate whether a module is
>> > > needed as
>> > > > I agree w/ Andy and others that we should not add this to the
>> import's
>> > > > description.  I don't think this kind of conformance text belongs
>> to the
>> > > > import's description.  If you think it is important to state this,
>> the
>> > > best
>> > > > Balázs Lengyel <balazs.lengyel=[email-masked]>
>> wrote:
>> > > > > As a draft author who was asked to add text about the imports IMHO
>> > > > >
>> > > > > *   it would be easy for me to remove the description from the
>> import.
>> > > > > Actually I really just want to know what is acceptable to the
>> group, so
>> > > I
>> > > > > can proceed
>> > > > > *   I also think that adding this text is in most cases easy and
>> it does
>> > > not
>> > > > > need updates later.
>> > > > > *   Imported parts are included in Xpath (augment, when, must,
>> require-
>> > > > > instance)
>> > > > >
>> > > > > *   Imported YAMs do not need to be implemented if only the
>> following
>> > > are
>> > > > > used
>> > > > >
>> > > > > *   Types
>> > > > > *   Features
>> > > > > *   extensions
>> > > > >
>> > > > > *   Ambiguous if
>> > > > >
>> > > > > *   groupings are used
>> > > > > needed. (E.g. notification-capabilities does not formally need
>> YANG-
>> > > > > Push
>> > > to
>> > > > > From: netmod <[email-masked]> On Behalf Of Andy Bierman
>> > > > > To: Ladislav Lhotka <[email-masked]>
>> > > > > Cc: NetMod WG <[email-masked]>
>> > > > > Subject: Re: [netmod] Text in import to indicate whether a module
>> is
>> > > > > On Thu, Dec 19, 2019 at 8:00 AM Ladislav Lhotka <[email-masked]
>> <mailto:
>> > > > > [email-masked]> > wrote:
>> > > > >
>> > > > > > On Thu, Dec 19, 2019 at 08:23:27AM +0100, Ladislav Lhotka wrote:
>> > > > > > > I don't see how YANG syntax defines this. If a module imports
>> > > > > > > - it just uses a typedef, such as "node-instance-identifier",
>> and
>> > > then
>> > > > > > > - it augments ietf-netconf-acm, which makes sense only if the
>> latter
>> > > > > > >   module is implemented.
>> > > > > > >
>> > > > > > > implemented or not, but the "import" statement itself doesn't
>> tell
>> > > you
>> > > > > > > anything.
>> > > > > > >
>> > > > > >
>> > > > > > Can we not assume that an implementor will figure out the
>> difference?
>> > > > >
>> > > > > module users may not. For example, if somebody is evaluating
>> whether
>> > > > > to use a module for their device or not, it is important to know
>> that
>> > > > > You seem to be talking about a new conformance documentation
>> procedure
>> > > > >
>> > > > > that attempts to solve the problem "to use modules A, B, and C
>> > > > > together
>> > > > >
>> > > > > to achieve some functionality X, all these conditions need to be
>> met"..
>> > > > >
>> > > > > IMO this is a much harder problem than something that can be
>> solved
>> > > > >
>> > > > > with extra description-stmt text. The writer is likely to get it
>> wrong
>> > > > > or not
>> > > > >
>> > > > > keep it up to date, so a tool to analyze the file seems like a
>> better
>> > > > > solution.
>> > > > >
>> > > > >
>> > > > >
>> > > > > Lada
>> > > > >
>> > > > >
>> > > > >
>> > > > >
>> > > > >
>> > > > > Andy
>> > > > >
>> > > > >
>> > > > >
>> > > > >
>> > > > > > Or someone writes a pyang plugin to determine from the schema
>> tree
> netmod mailing [email-masked]://www.ietf.org/mailman/listinfo/netmod
>
>
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 02 Mar 2020 19:23:16 +0100

On Mon, 2020-03-02 at 09:52 -0800, Andy Bierman wrote:
> and not mention the ones that are not required.  The module description-stmt
> is better

Modules that have to be implemented can be imported only once. Adding this
information to the import statement for such modules is IMO more effective than
having it in the module description. I don't get how it could become a problem.

Lada

> > > > > > conformance requirement but just an info from the module author
> > > > about the
> > > > > It adds a lot of extra work but more importantly the import-stmt is
> > > > the wrong
> > > > > place
> > > > 
> > > > > > > > > > - it just uses a typedef, such as "node-instance-
> > > > identifier", and
> > > > > > then
> > > > > > > > > > - it augments ietf-netconf-acm, which makes sense only if
> > > > the latter
> > > > > > > > > >   module is implemented.
> > > > > > > > > >

---

From: Andy Bierman <[email-masked]>
Date: Mon, 2 Mar 2020 10:37:06 -0800

> having it in the module description. I don't get how it could become a
I do not think this info helps very much. It is duplicate info.
It should be in the description-stmts for the objects defined in the module.
It is also self-evident (and defined in YANG) that if you augment some
external node
you have to implement the augmented module.

 This is the classic definition of a CLR.

Lada

Andy

> statements,
> important
> is not
> have
> effectively
> it is
> they are
> in need
> module
> belongs
> this,
> > > > > IMHO
> easy and
> must,
> need
> if
> evaluating
> to know
> documentation
> to be
> be
> get it
> like a
> schema

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Mon, 2 Mar 2020 18:37:33 +0000

> having it in the module description. I don't get how it could become a problem.

The question is how we make sure that text written by a human reflects
the actual facts. If tools can derive most of the import semantics
(i.e., generate a list of imported names and how they are used), why
not have a tooling answer instead of relying on manual work by authors
and reviewers?

/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/>

---

From: Benoit Claise <[email-masked]>
Date: Tue, 3 Mar 2020 09:44:57 +0100

Hi,
>
>
> On Mon, Mar 2, 2020 at 10:23 AM Ladislav Lhotka <[email-masked] 
>     > On Mon, Mar 2, 2020 at 8:57 AM Benoit Claise <[email-masked]
>     <mailto:[email-masked]>> wrote:
Well, I had in mind the module description
The "description-stmts for the objects defined in the module" is yet 
another place.
>  This is the classic definition of a CLR.
Trying to decompose the problem space ....
I believe it's common sense to include in the RFC text that 
ietf-netconf-acm is optional to implement (to take the example in 
question in 
https://tools.ietf.org/html/draft-ietf-netconf-notification-capabilities-11)
Do we agree that this information should also be contained somewhere, 
somehow in the YANG module? I would say: yes

If yes, what are the options?
I agree with Juergen (in a reply in this email thread): ideally a 
tooling answer would be better. This will take some time. So what do we 
do now?
3 options:
a. import description (description-stmt in import-stmt)

    module ietf-system-capabilities {
       yang-version 1.1;
       namespace
         "urn:ietf:params:xml:ns:yang:ietf-system-capabilities";
       prefix sysc;

       import ietf-netconf-acm
         { prefix nacm; }
         description "_ietf-netconf-acm is optional to implement_.";
         }

b. module description (description-stmt in  meta-stmts in 
module-stmt/submodule-stmt)

    module ietf-system-capabilities {
       yang-version 1.1;
       namespace
         "urn:ietf:params:xml:ns:yang:ietf-system-capabilities";
       prefix sysc;

       import ietf-netconf-acm { prefix nacm; }

       import ietf-yang-library {
         prefix yanglib;
         description "Revision 2019-01-04 or a
           revision derived from it is REQUIRED.";
       }

       organization
         "IETF NETCONF (Network Configuration) Working Group";
       contact
         "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
          WG List:  <mailto:[email-masked]>

          Editor:   Balazs Lengyel
                    <mailto:[email-masked]>";
       description
         "This module specifies a module intended to contain system
           capabilities. System capabilities may include capabilities of a
           NETCONF or RESTCONF server or a notification publisher.

           ...

           _ietf-netconf-acm is optional to implement."_

c. description-stmts for the objects defined in the module

               leaf node-selector {
                 type nacm:node-instance-identifier;
                 description
                   "Selects the data nodes for which capabilities are
                    specified. The special value '/' denotes all data nodes
                    in the datastore._ietf-netconf-acm is optional to implement._";
               }

c. looks weird to me, and might need repetitions in different YANG 
objects. In the end, as an implementer, I only care to understand 
whether I need to implement "ietf-netconf-acm" as a prequesite to 
implement ietf-system-capabilities.

Between a. and b., I have no strong preferences.
However, a. seems to be the logical place to me.

Regards, Benoit
>
>
>     >
>     > > Regards, Benoit
>     > >
>     >
>     > Andy
>     >
>     > > >
>     > > > On Wed, Jan 8, 2020 at 5:44 AM Ladislav Lhotka
>     <[email-masked] <mailto:[email-masked]>> wrote:
>     > > > > > On Wed, Jan 8, 2020 at 1:11 AM Ladislav Lhotka
>     <[email-masked] <mailto:[email-masked]>> wrote:
>     external
>     > > > > > > > Balázs Lengyel
>     <balazs.lengyel=[email-masked]
>     > > > > > > > > As a draft author who was asked to add text about
>     the imports
>     > > > > IMHO
>     > > > > > > > >
>     > > > > > > > > > On Thu, Dec 19, 2019 at 08:23:27AM +0100,
>     Ladislav Lhotka
>     > > > > wrote:

---

From: Andy Bierman <[email-masked]>
Date: Tue, 3 Mar 2020 08:13:58 -0800

> The "description-stmts for the objects defined in the module" is yet

The object descriptions are the correct level of granularity to be useful.
A boolean statement wrt/ module implementation is required vs not required
is not very useful.
Rarely is the entire module either fully required or nothing to implement
at all.

IMO it is wrong to conflate the import-stmt with conformance requirements.
It is merely a mechanism to bind local prefix usage to an external module.
Text like "revision X or derived from X is required" is appropriate for the
import-stmt because
it refers to the binding between prefix and imported module revision used.

Consider how this extra documentation work scales to a big module like
ietf-bgp.
There are multiple submodules, each with overlapping imports and each with
their own module header.

Andy

> ietf-netconf-acm is optional to implement (to take the example in question
> in
> I agree with Juergen (in a reply in this email thread): ideally a tooling
> answer would be better. This will take some time. So what do we do now?
> 3 options:
>     description "*ietf-netconf-acm is optional to implement*.";
>     }
>
>
>      WG List:  <mailto:[email-masked]> <[email-masked]>
>
>      Editor:   Balazs Lengyel
>                <mailto:[email-masked]> <[email-masked]>";
>   description
>       *ietf-netconf-acm is optional to implement."*
>
>                in the datastore. *ietf-netconf-acm is optional to implement.*";
>           }
>
>
> objects. In the end, as an implementer, I only care to understand whether I
> need to implement "ietf-netconf-acm" as a prequesite to implement
> ietf-system-capabilities.
>
>> author
>> Lhotka

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 5 Mar 2020 13:31:19 +0000

Hello,

Putting this information on individual schema nodes can be a problem if a module uses imported items a lot. We have modules with 100+ schema nodes that use an import, while  there are only 7 modules imported. Adding the statement (mandatory/optional to implement) 100 times would be a lot of text. I also doubt that people will check all 100 places.

IMHO alternatives a) or b) are feasible. (I like a) the best)

Regards Balazs

From: netmod <[email-masked]> On Behalf Of Andy Bierman
Sent: 2020. március 3., kedd 17:14
To: Benoit Claise <[email-masked]>
Cc: NETMOD WG <[email-masked]>
Subject: Re: [netmod] Text in import to indicate whether a module is needed as import-only or as implemented

On Tue, Mar 3, 2020 at 12:45 AM Benoit Claise <[email-masked] <mailto:[email-masked]> > wrote:

Hi,

On Mon, Mar 2, 2020 at 10:23 AM Ladislav Lhotka <[email-masked] <mailto:[email-masked]> > wrote:

On Mon, 2020-03-02 at 09:52 -0800, Andy Bierman wrote:
> 
> 
> On Mon, Mar 2, 2020 at 8:57 AM Benoit Claise <[email-masked] <mailto:[email-masked]> > wrote:

Well, I had in mind the module description
The "description-stmts for the objects defined in the module" is yet another place.

A boolean statement wrt/ module implementation is required vs not required is not very useful.

Rarely is the entire module either fully required or nothing to implement at all.

Text like "revision X or derived from X is required" is appropriate for the import-stmt because

Consider how this extra documentation work scales to a big module like ietf-bgp.

There are multiple submodules, each with overlapping imports and each with their own module header.

Andy

It is also self-evident (and defined in YANG) that if you augment some external node

Lada

Trying to decompose the problem space ....
I believe it's common sense to include in the RFC text that ietf-netconf-acm is optional to implement (to take the example in question in https://tools.ietf.org/html/draft-ietf-netconf-notification-capabilities-11)
Do we agree that this information should also be contained somewhere, somehow in the YANG module? I would say: yes

If yes, what are the options?
I agree with Juergen (in a reply in this email thread): ideally a tooling answer would be better. This will take some time. So what do we do now?
3 options:
a. import description (description-stmt in import-stmt) 

  import ietf-netconf-acm 
    { prefix nacm; }
    description "ietf-netconf-acm is optional to implement.";
    }

b. module description (description-stmt in  meta-stmts in module-stmt/submodule-stmt)

 
 
  organization
    "IETF NETCONF (Network Configuration) Working Group";
  contact
    "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
     WG List:   <mailto:[email-masked]> <mailto:[email-masked]>
 
     Editor:   Balazs Lengyel
                <mailto:[email-masked]> <mailto:[email-masked]>";
  description
    "This module specifies a module intended to contain system
      capabilities. System capabilities may include capabilities of a
      NETCONF or RESTCONF server or a notification publisher.
 
      ...

      ietf-netconf-acm is optional to implement."

          leaf node-selector { 
            type nacm:node-instance-identifier;
            description
              "Selects the data nodes for which capabilities are
               specified. The special value '/' denotes all data nodes
               in the datastore. ietf-netconf-acm is optional to implement.";
          }

c. looks weird to me, and might need repetitions in different YANG objects. In the end, as an implementer, I only care to understand whether I need to implement "ietf-netconf-acm" as a prequesite to implement ietf-system-capabilities. 

Regards, Benoit

>  
> > Regards, Benoit
> > 
> 
> Andy
>  
> > > 
> > > On Wed, Jan 8, 2020 at 5:44 AM Ladislav Lhotka <[email-masked] <mailto:[email-masked]> > wrote:
> > > > > On Wed, Jan 8, 2020 at 1:11 AM Ladislav Lhotka <[email-masked] <mailto:[email-masked]> > wrote:
> > > > > > > From: Martin Bjorklund <[email-masked] <mailto:[email-masked]> > 
> > > > > > > To: Balázs Lengyel <[email-masked] <mailto:[email-masked]> >
> > > > > > > Cc: [email-masked] <mailto:[email-masked]> ; [email-masked] <mailto:[email-masked]> ; [email-masked] <mailto:[email-masked]> 
> > > > > > > Balázs Lengyel <balazs.lengyel=[email-masked] <mailto:[email-masked]> >
> > > > wrote:
> > > > > > > > From: netmod <[email-masked] <mailto:[email-masked]> > On Behalf Of Andy Bierman
> > > > > > > > To: Ladislav Lhotka <[email-masked] <mailto:[email-masked]> >
> > > > > > > > Cc: NetMod WG <[email-masked] <mailto:[email-masked]> >
> > > > > > > > On Thu, Dec 19, 2019 at 8:00 AM Ladislav Lhotka <[email-masked] <mailto:[email-masked]> 
> > > > <mailto: <mailto:%0b> 
> > > > > > > > [email-masked] <mailto:[email-masked]> > > wrote:
> > > > > > > > 
> > > > > > > > [email-masked] <mailto:[email-masked]>  <mailto:[email-masked] <mailto:[email-masked]> >

---

From: Andy Bierman <[email-masked]>
Date: Thu, 5 Mar 2020 07:42:49 -0800

On Thu, Mar 5, 2020 at 5:31 AM Balázs Lengyel <[email-masked]>
wrote:

> Hello,
>
> Putting this information on individual schema nodes can be a problem if a
> module uses imported items a lot. We have modules with 100+ schema nodes
> that use an import, while  there are only 7 modules imported. Adding the
> statement (mandatory/optional to implement) 100 times would be a lot of
> text. I also doubt that people will check all 100 places.
>

This is a strawman -- nobody suggested duplicating the same text over and
over in data nodes.
The same issue exists with the reference-stmt.  We don't require (or
encourage) people to
place a reference to an external RFC on every leaf. The same judgement can
be used here.

Andy

>
>
> *From:* netmod <[email-masked]> *On Behalf Of *Andy Bierman
> *Sent:* 2020. március 3., kedd 17:14
> *To:* Benoit Claise <[email-masked]>
> *Cc:* NETMOD WG <[email-masked]>
> *Subject:* Re: [netmod] Text in import to indicate whether a module is
> <%0b>> > > > > > > > [email-masked]> > wrote:
> > > > > > > > >

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 5 Mar 2020 15:52:10 +0000

From: Andy Bierman <[email-masked]> 
Sent: 2020. március 5., csütörtök 16:43
To: Balázs Lengyel <[email-masked]>
Cc: Benoit Claise <[email-masked]>; NETMOD WG <[email-masked]>
Subject: Re: [netmod] Text in import to indicate whether a module is needed as import-only or as implemented

On Thu, Mar 5, 2020 at 5:31 AM Balázs Lengyel <[email-masked] <mailto:[email-masked]> > wrote:

Hello,

 

This is a strawman -- nobody suggested duplicating the same text over and over in data nodes.

The same issue exists with the reference-stmt.  We don't require (or encourage) people to

place a reference to an external RFC on every leaf. The same judgement can be used here.

Andy

 BALAZS2: If the first 50 uses of an import don’t need an implemented import-module  but the 51stdoes, then finding this will be difficult, unless we formalize it somehow e.g. with a new statement, extension, standard text, whatever.

From: netmod <[email-masked] <mailto:[email-masked]> > On Behalf Of Andy Bierman
Sent: 2020. március 3., kedd 17:14
To: Benoit Claise <[email-masked] <mailto:[email-masked]> >
Cc: NETMOD WG <[email-masked] <mailto:[email-masked]> >
Subject: Re: [netmod] Text in import to indicate whether a module is needed as import-only or as implemented

Hi,

 

 

Andy

Lada

 
  import ietf-netconf-acm 
    { prefix nacm; }

 

  organization
 
     Editor:   Balazs Lengyel
 
      ...

          leaf node-selector { 

Regards, Benoit

---

From: Andy Bierman <[email-masked]>
Date: Thu, 5 Mar 2020 08:34:26 -0800

On Thu, Mar 5, 2020 at 7:52 AM Balázs Lengyel <[email-masked]>
wrote:

>
>
>
>
> *From:* Andy Bierman <[email-masked]>
> *Sent:* 2020. március 5., csütörtök 16:43
> *To:* Balázs Lengyel <[email-masked]>
> *Cc:* Benoit Claise <[email-masked]>; NETMOD WG <[email-masked]>
>  BALAZS2: If the first 50 uses of an import don’t need an implemented
> import-module  but the 51stdoes, then finding this will be difficult,
> unless we formalize it somehow e.g. with a new statement, extension,
> standard text, whatever.
>

I am unclear on the procedures for this new procedure to be added to the
documentation of all YANG modules.

1) What does "implement" mean?
    Even in this case, implementation of a typedef is required.
    So does "implement" mean "implement data nodes"?
   How is "implement a leafref typedef" classified?

2) What is the module granularity?
   Is the same information repeated in each submodule?
   Does a submodule header document the implementation requirements
   just for that submodule?

3) What is the object granularity?
    Does the author search for every occurrence of the prefix and then
write a
    summary for that object? Does the author just stop when implementation
of
    a data node is required (making the boolean statement true)

Andy