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

From: Balázs Lengyel <[email-masked]>
Date: Wed, 18 Dec 2019 14:08:04 +0000

Hello Mahesh, 

I was asked by the group to include in each import statement whether the imported module is needed as import-only or as implemented. IMHO netmod/netconf group should agree on some standard text for model designers to use. Maybe the text proposed below can be used everywhere. The sentence starting with Revision yyyy-mm-dd  may not always be needed.

I propose the text  

  import ietf-netconf-acm  {

    prefix nacm;

    description

       "The module ietf-netconf-acm is OPTIONAL to implement.";

  }

  import ietf-yang-library {

    prefix yanglib;

    description "The module ietf-yang-library is REQUIRED to

      be implemented. Revision 2019-01-04 or a

      revision derived from it is REQUIRED.";

  }

Regards Balazs

P.S. In Yang-Next this could be a candidate for a formal substatement instead of a description text.

From: Mahesh Jethanandani <[email-masked]> 
Sent: 2019. december 18., szerda 3:20
To: Kent Watsen <[email-masked]>
Cc: Balázs Lengyel <[email-masked]>
Subject: Re: [netconf] New Version Notification for draft-ietf-netconf-notification-capabilities-08.txt

Hi Balazs,

Additionally, it would be important to address some of the normative text in the module. Specifically, we were looking at the following description statements:

  import ietf-yang-push    {
    prefix yp;
    description
      "This module requires ietf-yang-push to be implemented for the
        two subscription-capabilities containers.";
  }
  import ietf-yang-library {
    prefix yanglib;
    description "This module requires ietf-yang-library to
      be implemented. Revision 2019-01-04 or a
      revision derived from it is required.";
  }

The requirement in the description statement feels and smells like words one would use to signify requirements in a specification. However, you are not using any of the words like REQUIRED etc. to describe it. Why is it?

Mahesh Jethanandani

[email-masked] <mailto:[email-masked]>

---

From: Andy Bierman <[email-masked]>
Date: Wed, 18 Dec 2019 09:35:34 -0800

On Wed, Dec 18, 2019 at 6:08 AM Balázs Lengyel <balazs.lengyel=
[email-masked]> wrote:

> Hello Mahesh,
>
> I was asked by the group to include in each import statement whether the
> imported module is needed as import-only or as implemented. IMHO
> netmod/netconf group should agree on some standard text for model designers
> to use. Maybe the text proposed below can be used everywhere. The sentence
> starting with Revision yyyy-mm-dd  may not always be needed.
>
>
>
>
>
> I propose the text
>
>
>
> *       "The module ietf-netconf-acm is OPTIONAL to implement.";*
>
>   }
>
>
>
>     description *"The module ietf-yang-library is REQUIRED to*
>
> *      be implemented. Revision 2019-01-04 or a*
>
> *      revision derived from it is REQUIRED.";*
>
>   }
>
>
>
> Regards Balazs
>
>
>

IMO this is a bad idea.
The IETF keeps adding CLRs to YANG that make it harder to use over time.
The YANG syntax defines what must be implemented from the imported module,
so extra description-stmts just add more busy work for writers and
reviewers.
The text specifying the revision overrides (and breaks) YANG rules.
YANG 1.1 has specific import-by-revision that cannot be changed with a
description-stmt.

Andy

>
>
> *From:* Mahesh Jethanandani <[email-masked]>
> *Sent:* 2019. december 18., szerda 3:20
> *To:* Kent Watsen <[email-masked]>
> *Cc:* Balázs Lengyel <[email-masked]>
> *Subject:* Re: [netconf] New Version Notification for
> draft-ietf-netconf-notification-capabilities-08.txt
>
>
>
> Hi Balazs,
>
>
>
> Additionally, it would be important to address some of the normative text
> in the module. Specifically, we were looking at the following description
> statements:
>
>
>
>   import ietf-yang-push    {
>
>     prefix yp;
>
>     description
>
> The requirement in the description statement feels and smells like words
> one would use to signify requirements in a specification. However, you are
> not using any of the words like REQUIRED etc. to describe it. Why is it?
>
>
>
> Mahesh Jethanandani
>
> [email-masked]
>
>
>
>
>
>
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 19 Dec 2019 08:23:27 +0100

> The YANG syntax defines what must be implemented from the imported module,

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.

> YANG 1.1 has specific import-by-revision that cannot be changed with a

This is one of the problems that the semver effort aims to solve. What happens quite oftem these days is that a module is written for NMDA and thus needs NMDA versions of modules to be imported. But specifying an exact revision is really a bad idea.

Lada

-- 
Ladislav Lhotka 
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Thu, 19 Dec 2019 07:52:38 +0000

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

-- 
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: Ladislav Lhotka <[email-masked]>
Date: Thu, 19 Dec 2019 17:00:18 +0100

On Thu, 2019-12-19 at 07:52 +0000, Schönwälder, Jürgen wrote:
> > It it the YANG library that specifies whether a module is implemented or
> > not, but the "import" statement itself doesn't tell you anything.
> > 
> 

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).

Lada

---

From: Andy Bierman <[email-masked]>
Date: Thu, 19 Dec 2019 08:22:44 -0800

On Thu, Dec 19, 2019 at 8:00 AM Ladislav Lhotka <[email-masked]> wrote:

> > > I don't see how YANG syntax defines this. If a module imports
> ietf-netconf-
> > > acm, it could be because
> > >
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