Subject: [yang-doctors] Normative Language in YANG descriptions

From: "Acee Lindem (acee)" <[email-masked]>
Date: Wed, 16 Sep 2020 11:53:53 +0000

All,

I just received a comment on validation in a description statement for ietf-routing-policy. The comment was more of a question as whether “should” should be “SHOULD”. I looked at our existing published models and we have not been doing this consistently. Perhaps we SHOULD when it is normative validation.

Thanks,
Acee

---

From: Mahesh Jethanandani <[email-masked]>
Date: Wed, 16 Sep 2020 22:05:13 -0700

+1.

> On Sep 16, 2020, at 4:53 AM, Acee Lindem (acee) <acee=[email-masked]> wrote:
> 
> All, 
>  
> _______________________________________________
> yang-doctors mailing list
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/yang-doctors <https://www.ietf.org/mailman/listinfo/yang-doctors>
Mahesh Jethanandani
[email-masked]

---

From: Kent Watsen <[email-masked]>
Date: Thu, 17 Sep 2020 15:47:38 +0000

I use 2119 language in *all* my YANG modules because I want the YANG module to be the most-normative part of the draft (the single source of truth), with the other normative sections in the draft containing little to no duplicative text.  Thus most, if not all, of the semantics are captured in the YANG description statements.

To do this, I put the 2119 boiler template into the YANG module’s top-level description statement, so the module is understandable even in a standalone context, after being stripped from the final RFC.  For instance, see https://tools.ietf.org/html/rfc8572#section-6.3 <https://tools.ietf.org/html/rfc8572#section-6.3>.

Personally, I think all RFCs used to publish YANG modules should be written using 2119 language this way.

Kent

> On Sep 17, 2020, at 1:05 AM, Mahesh Jethanandani <[email-masked]> wrote:
> 
> +1.
> 
>> On Sep 16, 2020, at 4:53 AM, Acee Lindem (acee) <acee=[email-masked] <mailto:acee=[email-masked]>> wrote:
>> 
>> All, 
>>  
> [email-masked] <mailto:[email-masked]>
> 
> 
> 
> 
> 
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors

---

From: Andy Bierman <[email-masked]>
Date: Thu, 17 Sep 2020 09:00:04 -0700

Hi,

I think all YANG module text is normative, unless it is a special example
module.
This has been an issue forever (starting with MIBs). How much normative
text to put
in the text sections vs. the module itself?  The worst outcome is the
"partial rewrite"
where there is normative text in multiple places and it doesn't quite align.

Andy

On Thu, Sep 17, 2020 at 8:47 AM Kent Watsen <[email-masked]> wrote:

> I use 2119 language in *all* my YANG modules because I want the YANG
> module to be the most-normative part of the draft (the single source of
> truth), with the other normative sections in the draft containing little to
> no duplicative text.  Thus most, if not all, of the semantics are captured
> in the YANG description statements.
>
> To do this, I put the 2119 boiler template into the YANG module’s
> top-level description statement, so the module is understandable even in a
> standalone context, after being stripped from the final RFC.  For instance,
> see https://tools.ietf.org/html/rfc8572#section-6.3.
>
> I just received a comment on validation in a description statement for
> ietf-routing-policy. The comment was more of a question as whether “should”
> should be “SHOULD”. I looked at our existing published models and we have
> not been doing this consistently. Perhaps we SHOULD when it is normative
> validation.
>
> Thanks,
> Acee

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 17 Sep 2020 18:08:58 +0200

Quoting RFC 8174 (BCP 14):

   o  These words can be used as defined here, but using them is not
      required.  Specifically, normative text does not require the use
      of these key words.  They are used for clarity and consistency
      when that is what's wanted, but a lot of normative text does not
      use them and is still normative.

/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: Andy Bierman <[email-masked]>
Date: Thu, 17 Sep 2020 09:21:45 -0700

>       use them and is still normative.

The decision criteria for using 2119 keywords is not different for plain
text vs. YANG module description-stmts.
I tend to agree with Kent that they should (or is it SHOULD :-) be used in
YANG modules.

Andy

> see https://tools.ietf.org/html/rfc8572#section-6.3 <
> https://tools.ietf.org/html/rfc8572#section-6.3>.
> >
> > >> On Sep 16, 2020, at 4:53 AM, Acee Lindem (acee) <acee=
> [email-masked] <mailto:acee=[email-masked]>>
> wrote:
> > >>
> > >> All,
> > >>
> > >> I just received a comment on validation in a description statement
> for ietf-routing-policy. The comment was more of a question as whether
> “should” should be “SHOULD”. I looked at our existing published models and
> we have not been doing this consistently. Perhaps we SHOULD when it is
> normative validation.
> > >>
> > >> Thanks,
> > >> Acee
> > >> https://www.ietf.org/mailman/listinfo/yang-doctors <
> https://www.ietf.org/mailman/listinfo/yang-doctors>
> > > Mahesh Jethanandani

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 17 Sep 2020 18:29:40 +0200

I believe it is up to the author/wg/iesg member of the day.

/js

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Thu, 17 Sep 2020 16:30:53 +0000

I’ve done this in the ietf-routing-policy.yang in draft-ietf-rtgwg-policy-model-24

From: Andy Bierman <[email-masked]>
Date: Thursday, September 17, 2020 at 12:22 PM
To: Juergen Schoenwaelder <[email-masked]>, Kent Watsen <[email-masked]>, Mahesh Jethanandani <[email-masked]>, YANG Doctors <[email-masked]>, Acee Lindem <[email-masked]>
Subject: Re: [yang-doctors] Normative Language in YANG descriptions

On Thu, Sep 17, 2020 at 9:09 AM Juergen Schoenwaelder <[email-masked]<mailto:[email-masked]>> wrote:
Quoting RFC 8174 (BCP 14):

The decision criteria for using 2119 keywords is not different for plain text vs. YANG module description-stmts.
I tend to agree with Kent that they should (or is it SHOULD :-) be used in YANG modules.

/js

Andy

On Thu, Sep 17, 2020 at 03:47:38PM +0000, Kent Watsen wrote:
> > On Sep 17, 2020, at 1:05 AM, Mahesh Jethanandani <[email-masked]<mailto:[email-masked]>> wrote:
> >
> > +1.
> >
> >> On Sep 16, 2020, at 4:53 AM, Acee Lindem (acee) <acee=[email-masked]<mailto:[email-masked]> <mailto:acee<mailto:acee>=[email-masked]<mailto:[email-masked]>>> wrote:
> >>
> >> All,
> >>
> >> [email-masked]<mailto:[email-masked]> <mailto:[email-masked]<mailto:[email-masked]>>
> > [email-masked]<mailto:[email-masked]> <mailto:[email-masked]<mailto:[email-masked]>>
> >
> >
> >
> >
> >
> > [email-masked]<mailto:[email-masked]>

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

_______________________________________________
yang-doctors mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/yang-doctors