Subject: [netmod] example modules in 6087bis

From: Martin Bjorklund <[email-masked]>
Date: Mon, 16 Jan 2017 16:48:03 +0100 (CET)

Hi,

It turns out that the recommendations on example modules are a bit
unclear.  Different drafts do very different things.  Some examples:

https://tools.ietf.org/html/draft-ietf-i2rs-yang-l3-topology-08#section-6.1.2

This example module really looks like a real module.  It uses an
IANA-controlled namespace, and the meta-statements indicate that this
is a normative modules.  But the module does not use the <CODE> tags.

https://tools.ietf.org/html/draft-ietf-netconf-restconf-18#appendix-C.1

This module is better, but it is written to follow RFC 6087 rules
(pass pyang --ietf), with the result that it contains a bit of "noise"
with some meaningless descriptions and meta-statements.  It also does
not use <CODE> tags.

A good example (IMO) is found in
https://tools.ietf.org/html/rfc8022#appendix-C

It uses descriptions when necessary (high s/n), no fake
meta-statements etc.

However, it might be a good idea to require example modules to have a
"description" statement that explains what the module examplifies.
For example, the example-rip could have:

  description
    "This example module demonstrates how the core routing data model
     can be extended to support a new control-plane protocol.  It is
     intended as an illustration rather than a real definition of a
     data model for the Routing Information Protocol (RIP).";

I think that 6087bis is clear when it says:

  The guidelines in this document refer mainly to a normative complete
  module or submodule, but may be applicable to example modules and
  YANG fragments as well.

I think this states that example modules do not have to pass pyang
--ietf.

In order to make this more clear, I suggest the following changes to
draft-ietf-netmod-rfc6087bis-09

In the Terminology section 2.4:

NEW:

  o  Example module:  A complete YANG module or submodule that is
     intended to illustrate some specific aspect, but not intended for
     actual use.

In section 4:

NEW:

   All normative modules or submodules, example modules or submodules,
   and example YANG fragments MUST be valid according to RFC 7950,
   except when they are used to illustrate some illegal constructs.

In Section 4.2.1 "Example Modules":

NEW:

  An example module SHOULD have a namespace on the form

    o  http://example.com/<module-name> OR
    o  urn:example:<module-name>

  An example module SHOULD have a description statement that describes
  that it is an example module, and what it examplifies.

  An example module SHOULD NOT have any additional meta-statements
  (i.e., "organization", "contact", or "reference").

  An example module SHOULD use the "description" statement in any
  definition where it is required to understand the example.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 17 Jan 2017 10:11:58 -0800

> is a normative modules.  But the module does not use the <CODE> tags.

This example needs to be redone.

There are 2 conflicting goals that need to be addressed.

1) Clearly identify a module as an example; not meant to be implemented;
    only present to demonstrate protocol interactions with an example module

2) Teach people good YANG authoring habits
     Way too much cut-and-paste out there so maybe if the examples
     follow "pyang --ietf" people will learn the right way to construct a
module

> It uses descriptions when necessary (high s/n), no fake

It does not have a revision-stmt, which is really important
for real YANG modules.

IMO the random set of description-stmts is no better or worse
than the examples in the RESTCONF draft.

>      data model for the Routing Information Protocol (RIP).";
OK

> I think this states that example modules do not have to pass pyang

I agree that examples do not need to pass with the --ietf flag.
But is the guideline a SHOULD pass or MAY pass?
(agree it is not MUST pass)

>   definition where it is required to understand the example.

new text is OK with me.
I would make it clear that module description and revision
SHOULD be present. All other optional clauses MAY be present.

> /martin
Andy

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

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 18 Jan 2017 10:52:33 +0100 (CET)

>     only present to demonstrate protocol interactions with an example module

Yes - maybe add this text to 6087bis?

>      follow "pyang --ietf" people will learn the right way to construct a

This assumes that people copy&paste from example modules.  I'm not
sure that this a real problem.  If they do that when they develop IETF
modules, Benoit's script will kick in anyway.

> It does not have a revision-stmt, which is really important

Yes, but it is not important for examples (typically).

> (agree it is not MUST pass)

The current text implies MAY.  Perhaps s/may/MAY/ in the original text
in order to make this clear?

/martin

---

From: Benoit Claise <[email-masked]>
Date: Wed, 18 Jan 2017 18:12:38 +0100

Martin,
> (pass pyang --ietf), with the result that it contains a bit of "noise"
It takes a lot of YANG experience to be able to distinguish what is 
noise or not.
>       intended to illustrate some specific aspect, but not intended for
It doesn't solve this issue, because 
https://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-09#section-4.2.1 
says:

      The <CODE BEGINS> convention SHOULD be used for complete example
      modules, but not YANG fragments.

That implies to me that we have 3 types:
1. _complete _example modules => I read it that they must pass pyang 
-ietf, SHOULD have <CODE BEGINS>
     If there is <CODE BEGINS>, it's because people will want to extract 
it, and play with it. So the tools chain must work
2. the other example modules. No <CODE BEGINS>. I guess they don't pass 
pyang
3. YANG fragments. No <CODE BEGINS>. I guess they don't pass pyang

In practice, 2 and 3 are the same. So we need just two definition

Scrap "complete" would help but that's not enough:

  The <CODE BEGINS> convention SHOULD be used for example
  modules, but not YANG fragments.

We only need to clarify 3 points
     <CODE BEGINS>, yes/no
     pyang, yes/no
     pyang --ietf yes/no

I guess we want, putting all this together:

   o  Example module:  A complete YANG module or submodule that is
      intended to illustrate some specific aspect, but not intended for
      actual use. Example module MUST be valid according to RFC 7950,
      except when they are used to illustrate some illegal constructs.
      Example module MAY be valid according to the rules in this document.

   o  YANG fragment:  A incomplete YANG module or submodule that is
      intended to illustrate some specific aspect, but not intended for
      actual use. YANG fragments MUST be valid according to RFC 7950,
      except when they are used to illustrate some illegal constructs.

  The <CODE BEGINS> convention SHOULD be used for example
  modules that pass validation according to RFC 7950.

  The <CODE BEGINS> convention MUST NOT be used for YANG fragment
  and for example modules that are used to illustrate some illegal constructs
  (therefore failing validation according to RFC 7950).

>     except when they are used to illustrate some illegal constructs.
We wouldn't need this if you take my proposal
>    definition where it is required to understand the example.
Fine.

Note that the RESTCONF RFC publication depends on this RFC6087bis 
convention. So let's quickly come to a conclusion.

Regards, Benoit
> .

---

From: Andy Bierman <[email-masked]>
Date: Wed, 18 Jan 2017 10:00:21 -0800

On Wed, Jan 18, 2017 at 9:12 AM, Benoit Claise <[email-masked]> wrote:

> It takes a lot of YANG experience to be able to distinguish what is noise
> or not.
>

I agree.  I see Martin's point though -- maintenance clauses like contact
and organization
are not really needed for examples.

> A good example (IMO) is found inhttps://tools.ietf.org/html/rfc8022#appendix-C
>
> It doesn't solve this issue, because https://tools.ietf.org/html/
> draft-ietf-netmod-rfc6087bis-09#section-4.2.1 says:
>
> 1. *complete *example modules => I read it that they must pass pyang
This is good
I prefer:
   - MUST use CODE BEGINS for a real module
   - MUST NOT use CODE BEGINS for an example module

   - MUST pass pyang --ietf for a real module
   - MUST pass pyang for example module

I have already received private emails about implementing the
example-jukebox
module in RESTCONF as part of the standard.  We already have operational
experience that people can be confused by the example modules, and
think they are supposed to be implemented for RFC compliance.

>  (therefore failing validation according to RFC 7950).
This text concerns me a little
We are not following the <CODE BEGINS> anywhere for examples.
the tools are extracting anything that starts "module blah".
IMO this makes it easier to confuse real and example modules.
I would prefer to consider only real modules as Code Components.

(We collect broken modules to test the compiler in modules/test/fail folder,
so even bad modules might be extracted.)

Andy

> netmod mailing [email-masked]://www.ietf.org/mailman/listinfo/netmod
> .
>
>
>
>

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 19 Jan 2017 11:00:50 +0100 (CET)

> >      except when they are used to illustrate some illegal constructs.

Fine with me.

>    - MUST NOT use CODE BEGINS for an example module

I agree (see below)

>    - MUST pass pyang for example module

Yes, this follows from Benoit's proposed text above.

> I would prefer to consider only real modules as Code Components.

I agree.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 19 Jan 2017 14:27:24 +0100

> It takes a lot of YANG experience to be able to distinguish what is 

I think it is up to the document author to design the example module so
as to convey the idea that the example illustrates, and sometimes it's
best to use bare statements, and descriptions would really be just
noise.

>   (therefore failing validation according to RFC 7950).

One option for automatic tools might be to parse module registrations in
IANA Considerations, and require --ietf compliance only for these
modules. Other modules demarcated with <CODE BEGINS/ENDS> would just
need to be plain valid, as you write.

Lada

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

---

From: Benoit Claise <[email-masked]>
Date: Mon, 23 Jan 2017 18:46:44 +0100

On 1/18/2017 7:00 PM, Andy Bierman wrote:
>
>
> On Wed, Jan 18, 2017 at 9:12 AM, Benoit Claise <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     Martin,
>>     Hi,
>>
>>     <https://tools.ietf.org/html/draft-ietf-i2rs-yang-l3-topology-08#section-6.1.2>
>>
>>     <https://tools.ietf.org/html/draft-ietf-netconf-restconf-18#appendix-C.1>
>>
>     It takes a lot of YANG experience to be able to distinguish what
>     is noise or not. 
>
> I agree.  I see Martin's point though -- maintenance clauses like 
> contact and organization
>>     <https://tools.ietf.org/html/rfc8022#appendix-C>
>>
>     <https://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-09#section-4.2.1>
>     says:
>
>     That implies to me that we have 3 types: 1. _complete _example
>     modules => I read it that they must pass pyang -ietf, SHOULD have
>     <CODE BEGINS>     If there is <CODE BEGINS>, it's because people
>     will want to extract it, and play with it. So the tools chain must
>     work 2. the other example modules. No <CODE BEGINS>. I guess they
>     don't pass pyang 3. YANG fragments. No <CODE BEGINS>. I guess they
>     don't pass pyang In practice, 2 and 3 are the same. So we need
>     just two definition Scrap "complete" would help but that's not
>     enough:
>
>     We only need to clarify 3 points     <CODE BEGINS>, yes/no    
>     pyang, yes/no     pyang --ietf yes/no I guess we want, putting all
>     this together:
>
Fine with me. Consistency is key here. Is it time to conclude this 
discussion? Regards, Benoit
>>          ohttp://example.com/<module-name> OR
>     Fine. Note that the RESTCONF RFC publication depends on this
>     RFC6087bis convention. So let's quickly come to a conclusion.
>     Regards, Benoit
>
> Andy
>
>>     /martin
>>
>>     [email-masked] <mailto:[email-masked]>
>>     <https://www.ietf.org/mailman/listinfo/netmod>
>>     .
>>
>     _______________________________________________ netmod mailing
>     list [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/netmod> 
>

---

From: Kent Watsen <[email-masked]>
Date: Tue, 24 Jan 2017 19:05:10 +0000

Hi Andy,

I think this discussion has come to a head.  Please submit an updated 6087bis as soon as you can.  Some comments:

1) on the 3rd line below, should the text clarify that --ietf is only for IETF modules?  Also, how does the MUST here jive with the SHOULD in Section 4.10?

2) related to #1, Section 5 says "In general, modules in IETF Standards Track specifications MUST comply with all syntactic and semantic requirements of YANG [RFC7950]."

   First, what does "In general...MUST" mean?  - maybe the 
   sentence should start with "Modules in IETF..."?

   Second, can we add a statement for non-IETF SDOs that might
   have other conventions/restrictions?  Would we recommend
   --strict for starters, until they can add an SDO-specific
   flag (e.g., --<sdo>) to pyang?

3) The first paragraph in Section 4.6 isn't clear, how about this?

 OLD
   This section contains the module(s) defined by the specification.
   These modules SHOULD be written using the YANG syntax defined in
   [RFC7950].  YANG 1.0 [RFC6020] MAY be used if no YANG 1.1 constructs
   or semantics are needed in the module.

 NEW
   This section contains the module(s) defined by the YANG specification.
   These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax;
   YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs
   or semantics are needed in the module.

 Note: this reads better, but I wonder, since YANG 1.0 syntax is a
 subset of YANG 1.1 syntax, what is really being said here? - that
 yang-version statement is optional?  Or maybe, instead of focusing
 on syntax, the statement should regard the version of YANG used?

4) Lastly, picking up on this discussion:

     https://www.ietf.org/mail-archive/web/netmod/current/msg17277.html.

   can add an Informational reference to RFC 4151 in Section 5.9?
   Maybe something like this:

 OLD

   The following examples are for non-Standards-Track modules.  The
   domain "example.com" SHOULD be used in all namespace URIs for example
   modules.

       http://example.com/ns/example-interfaces

       http://example.com/ns/example-system

 NEW

   The following URIs exemplify what might be used by non Standards
   Track modules.  Note that the domain "example.com" SHOULD be used
   by example modules in IETF drafts.

   Example URIs using URLs per RFC 3986 [RFC3986]:

       http://example.com/ns/example-interfaces
       http://example.com/ns/example-system

   Example URIs using tags per RFC 4151 [RFC4151]:
 
       tag:example.com,2017:example-interfaces
       tag:example.com,2017:example-system

Thanks,
Kent    // as shepherd

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 24 Jan 2017 20:26:30 +0100 (CET)

>    flag (e.g., --<sdo>) to pyang?

We wouldn't talk about any specific tool; we'd just talk about
compliance with this document.  Other SDOs will have to decide on
their own rules, but we can suggest that they use all our rules except
the naming convention for modules and namespaces.

>  on syntax, the statement should regard the version of YANG used?

The point is that yang-version 1.1 SHOULD be used, and yang-version 1
MAY be used.

>        tag:example.com,2017:example-system

I would like to see urn:example:<module-name>, that's what I usually
use here.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 24 Jan 2017 11:34:12 -0800

Hi,

On Tue, Jan 24, 2017 at 11:26 AM, Martin Bjorklund <[email-masked]> wrote:

> > I think this discussion has come to a head.  Please submit an updated
> 6087bis as soon as you can.  Some comments:
> >
> >
> > 1) on the 3rd line below, should the text clarify that --ietf is only
> for IETF modules?  Also, how does the MUST here jive with the SHOULD in
> Section 4.10?
> >
> > 2) related to #1, Section 5 says "In general, modules in IETF Standards
> Track specifications MUST comply with all syntactic and semantic
> requirements of YANG [RFC7950]."
> >

I would like the --ietf parameter to be renamed --normative so it is not
IETF-specific
and it is clear IETF example modules should not use it.
Probably too late for that.

Agree wrt/ naming conventions.
e.g., openconfig uses ALL_CAPS for identityrefs and IETF does not.

Andy

---

From: Kent Watsen <[email-masked]>
Date: Tue, 24 Jan 2017 20:56:12 +0000

Hi Martin,

> I would like to see urn:example:<module-name>, that's what
> I usually use here.

You mean the NID from RFC 6963?  Sure, that can be mentioned
as well but, unlike the other two examples, it's *only* useful
for examples...it does not represent a template that could be
used in production.

Kent // as a contributor

---

From: Benoit Claise <[email-masked]>
Date: Wed, 25 Jan 2017 15:18:55 +0100

On 1/24/2017 8:26 PM, Martin Bjorklund wrote:
> We wouldn't talk about any specific tool;
Note that the document does already.
See section 4.4:

    The 'pyang' compiler can be used to produce the tree diagram, using
        the '-f tree' command line parameter.

        If the YANG module is comprised of groupings only, then the tree
        diagram SHOULD contain the groupings.  The 'pyang' compiler can be
        used to produce a tree diagram with groupings using the '-f tree
        --tree-print-groupings" command line parameters.

Reviewing this yesterday, I was wondering: why not speak of yanglint?
In discussion with Radek about this, he mentioned:

    yes, libyang supports the tree format. However, in some details it differs from pyang:

    - instead of the module prefixes, we use module names to avoid prefix collisions.
    - additionally, the default values (of the the leaf/leaf-lists/choice) are printed

regards, Benoit
> we'd just talk about

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 25 Jan 2017 15:25:35 +0100 (CET)

Benoit Claise <[email-masked]> wrote:
> >> for IETF modules?  Also, how does the MUST here jive with the SHOULD
> >> in Section 4.10?
> >>
> >> 2) related to #1, Section 5 says "In general, modules in IETF
> >> Standards Track specifications MUST comply with all syntactic and
> >> semantic requirements of YANG [RFC7950]."
> >>

Ok.

> Reviewing this yesterday, I was wondering: why not speak of yanglint?

Ok, well I just didn't want to push any specific tool.  It is fine if
the doc mentions some tools that gets the job done.

/martin

---

From: Mahesh Jethanandani <[email-masked]>
Date: Wed, 25 Jan 2017 17:59:01 -0800

> On Jan 25, 2017, at 6:18 AM, Benoit Claise <[email-masked]> wrote:
> 
>> Kent Watsen <[email-masked]> <mailto:[email-masked]> wrote:
>>> Hi Andy,
>>> 
>>> 1) on the 3rd line below, should the text clarify that --ietf is only for IETF modules? 
Yes, and in addition yangvalidator.com <http://yangvalidator.com/> should stop complaining about module names and namespaces for modules that belong to other SDOs.

mef-cfm.yang:1: warning: RFC 6087: 4.1: the module name should start with one of the strings "ietf-" or "iana-"
mef-cfm.yang:3: warning: RFC 6087: 4.8: namespace value should be "urn:ietf:params:xml:ns:yang:mef-cfm"

>>>  Also, how does the MUST here jive with the SHOULD in Section 4.10?
>>> 
>>>      https://www.ietf.org/mail-archive/web/netmod/current/msg17277.html <https://www.ietf.org/mail-archive/web/netmod/current/msg17277.html>.
>>> 
>>>        http://example.com/ns/example-interfaces <http://example.com/ns/example-interfaces>
>>> 
>>>        http://example.com/ns/example-system <http://example.com/ns/example-system>
>>> 
>>>  NEW
>>> 
>>>        http://example.com/ns/example-interfaces <http://example.com/ns/example-interfaces>
>>>        http://example.com/ns/example-system <http://example.com/ns/example-system>
>>> 

Mahesh Jethanandani
[email-masked]