Subject: [netmod] proposal to add 2 new guidelines in 6087bis

From: Andy Bierman <[email-masked]>
Date: Fri, 27 Jan 2017 11:23:09 -0800

Hi,

The "pyang --ietf" validator checks the statement order used in
data-def-stmts.
There is no guideline that says this is required.
RFC 7950 says canonical order is RECOMMENDED.

1) data-def sub-statement order
Proposal: add new last sentence to sec. 4.6, para 3:

YANG data definition sub-statements SHOULD be specified in canonical order.

2) enum/bit statement ordering

Proposal: add new para 2 to  sec 5.11.3:

The 'enum' statements within an 'enumeration' data type SHOULD be
specified in ascending order, based on the implied and/or explicit values
of the 'value' sub-statement. The 'bit' statements within a 'bits' data type
SHOULD be specified in ascending order, based on the implied and/or
explicit values of the 'position' sub-statement.

Andy

---

From: Mahesh Jethanandani <[email-masked]>
Date: Fri, 27 Jan 2017 15:06:29 -0800

> On Jan 27, 2017, at 11:23 AM, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 
> The "pyang --ietf" validator checks the statement order used in data-def-stmts.

Not 6087bis specific …

But is this IETF module specific? If not, should this not be checked by pyang for all modules.

> explicit values of the 'position' sub-statement.

Ditto.

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

Mahesh Jethanandani
[email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Fri, 27 Jan 2017 15:18:38 -0800

Hi,

I think these guidelines should apply to other modules but using --ietf
with pyang is up
to the SDOs to decide.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 28 Jan 2017 11:54:25 +0100

> On 27 Jan 2017, at 20:23, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 

IMO, this adds nothing to what's already stated in 7950. According to RFC 2119, SHOULD and RECOMMENDED mean the same.

> explicit values of the 'position' sub-statement.

I don't agree. For some enumerations, especially those with a large number of enums, it is much more useful for the reader to have the enums ordered differently, e.g. alphabetically or geographically. On the other hand, numeric enum values often need to be assigned in the order how enums are defined in subsequent revisions.

Lada

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

---

From: Andy Bierman <[email-masked]>
Date: Sat, 28 Jan 2017 08:23:01 -0800

On Sat, Jan 28, 2017 at 2:54 AM, Ladislav Lhotka <[email-masked]> wrote:

> IMO, this adds nothing to what's already stated in 7950. According to RFC
> 2119, SHOULD and RECOMMENDED mean the same.
>
>

OK

> I don't agree. For some enumerations, especially those with a large number
> of enums, it is much more useful for the reader to have the enums ordered
> differently, e.g. alphabetically or geographically. On the other hand,
> numeric enum values often need to be assigned in the order how enums are
> defined in subsequent revisions.
>
>

We have been using ascending order in MIB modules and YANG modules
all along.  I think there are about 5000 modules in ascending order and one
not
in ascending order.  The guideline is SHOULD anyway.

YANG prohibits the value or position numbers from changing in
a new revision, so preserving previous ordering is required.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 30 Jan 2017 09:21:02 +0100

> On 28 Jan 2017, at 17:23, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> all along.  I think there are about 5000 modules in ascending order and one not

A guideline with little or no technical merit is just noise.

> a new revision, so preserving previous ordering is required.

This is of course only true for auto-numbering. I think 6087bis should instead include a guideline saying that explicit values should be specified for extensible enumerations so that new enums can be inserted where it makes most sense, also in the middle of the list.

Extensibility is probably less relevant for "bits" type because available bits are usually pre-allocated. But then again, some authors may prefer listing bits in the descending order of positions, as in the ietf-isis-sr module:

https://tools.ietf.org/html/draft-ietf-isis-sr-yang-00#section-4

Lada

---

From: William Lupton <[email-masked]>
Date: Mon, 30 Jan 2017 11:13:01 +0000

Note that pyang --ietf is just a thin wrapper around --lint, with IETF/IANA namespace and module prefixes.

At BBF we are happy to follow IETF recommendations, and require no warnings or errors when using:

--strict --max-line-length=70 --lint --lint-modulename-prefix=bbf --lint-namespace-prefix=urn:bbf:yang:

William

> On 27 Jan 2017, at 23:18, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 
> I think these guidelines should apply to other modules but using --ietf with pyang is up
> to the SDOs to decide.
> 
> 
> Andy
> 
> 
> On Fri, Jan 27, 2017 at 3:06 PM, Mahesh Jethanandani <[email-masked] <mailto:[email-masked]>> wrote:
> 
>> On Jan 27, 2017, at 11:23 AM, Andy Bierman <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> Hi,
>> 
>> [email-masked] <mailto:[email-masked]>
>> https://www.ietf.org/mailman/listinfo/netmod <https://www.ietf.org/mailman/listinfo/netmod>
> 
> Mahesh Jethanandani
> [email-masked] <mailto:[email-masked]>
> 
> 
> 
>

---

From: Robert Wilton <[email-masked]>
Date: Mon, 30 Jan 2017 11:38:24 +0000

Hi Andy, Lada,

On 28/01/2017 16:23, Andy Bierman wrote:
>
>
> On Sat, Jan 28, 2017 at 2:54 AM, Ladislav Lhotka <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>
>     > On 27 Jan 2017, at 20:23, Andy Bierman <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     >
>     > Hi,
>     >
>     IMO, this adds nothing to what's already stated in 7950. According
>     to RFC 2119, SHOULD and RECOMMENDED mean the same.
>
I support Andy's recommendation here, although I think that it might 
also be useful to cross reference back to where the canonical order is 
actually defined in 7950.

Lada, you are right that 7950 recommends the correct ordering, but I 
think that it is buried with the ABNF, which won't necessarily be read 
by all users of YANG.  Pulling it out in 6087bis doesn't seem to do any 
harm.

>     I don't agree. For some enumerations, especially those with a
>     large number of enums, it is much more useful for the reader to
>     have the enums ordered differently, e.g. alphabetically or
>     geographically. On the other hand, numeric enum values often need
>     to be assigned in the order how enums are defined in subsequent
>     revisions.
>
>
>
+1.  Isn't this exactly what a SHOULD statement means.  I.e. put in 
ascending order unless there is a good reason not to do so (e.g. as per 
Lada's examples), in which case that is fine.

Rob

>     <https://www.ietf.org/mailman/listinfo/netmod>
>
>     --

---

From: Andy Bierman <[email-masked]>
Date: Mon, 30 Jan 2017 09:52:33 -0800

On Mon, Jan 30, 2017 at 3:38 AM, Robert Wilton <[email-masked]> wrote:

>> I support Andy's recommendation here, although I think that it might also
> be useful to cross reference back to where the canonical order is actually
> defined in 7950.
>
> Lada, you are right that 7950 recommends the correct ordering, but I think
> that it is buried with the ABNF, which won't necessarily be read by all
> users of YANG.  Pulling it out in 6087bis doesn't seem to do any harm.
>
>
>
Actually, the RFC 7950 text is not really correct.
The canonical order does not apply to the relative order of
container, list, leaf-list, leaf, choice, case, anyxml, or anydata.

We list these nodes in the relative order we want in the data structure,
not all containers first, then all leafs, etc.  That is why my text says
'data definition sub-statements'.

Andy

>> I don't agree. For some enumerations, especially those with a large
>> number of enums, it is much more useful for the reader to have the enums
>> ordered differently, e.g. alphabetically or geographically. On the other
>> hand, numeric enum values often need to be assigned in the order how enums
>> are defined in subsequent revisions.
>>
>>
>
> netmod mailing [email-masked]://www.ietf.org/mailman/listinfo/netmod
>
>
>

---

From: Robert Wilton <[email-masked]>
Date: Mon, 30 Jan 2017 18:09:48 +0000

On 30/01/2017 17:52, Andy Bierman wrote:
>
>
> On Mon, Jan 30, 2017 at 3:38 AM, Robert Wilton <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     Hi Andy, Lada,
>
>
>>         IMO, this adds nothing to what's already stated in 7950.
>>         According to RFC 2119, SHOULD and RECOMMENDED mean the same.
>>
>     I support Andy's recommendation here, although I think that it
>     might also be useful to cross reference back to where the
>     canonical order is actually defined in 7950.
>
>     Lada, you are right that 7950 recommends the correct ordering, but
>     I think that it is buried with the ABNF, which won't necessarily
>     be read by all users of YANG. Pulling it out in 6087bis doesn't
>     seem to do any harm.
>
>
>

Is this worth adding as an errata to 7950 then?

From:

    data-def-stmt       = container-stmt /
                          leaf-stmt /
                          leaf-list-stmt /
                          list-stmt /
                          choice-stmt /
                          anydata-stmt /
                          anyxml-stmt /
                          uses-stmt

To:
    data-def-stmt       = ;; these stmts can appear in any order
                          container-stmt /
                          leaf-stmt /
                          leaf-list-stmt /
                          list-stmt /
                          choice-stmt /
                          anydata-stmt /
                          anyxml-stmt /
                          uses-stmt

Otherwise, if I am reading it correctly, it seems to imply that the top 
level data-defn stmts in a module/sub-module must be in the order above?

Rob

>>         large number of enums, it is much more useful for the reader
>>         to have the enums ordered differently, e.g. alphabetically or
>>         geographically. On the other hand, numeric enum values often
>>         need to be assigned in the order how enums are defined in
>>         subsequent revisions.
>>
>>
>>
>     ascending order unless there is a good reason not to do so (e.g.
>     as per Lada's examples), in which case that is fine.
>
>     Rob
>
>
>>

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 30 Jan 2017 21:07:44 +0100

> On 30 Jan 2017, at 19:09, Robert Wilton <[email-masked]> wrote:
> 
> 
> 
>> I support Andy's recommendation here, although I think that it might also be useful to cross reference back to where the canonical order is actually defined in 7950.
>> 
>> Lada, you are right that 7950 recommends the correct ordering, but I think that it is buried with the ABNF, which won't necessarily be read by all users of YANG.  Pulling it out in 6087bis doesn't seem to do any harm.
>> 
>> 
>> 
> Otherwise, if I am reading it correctly, it seems to imply that the top level data-defn stmts in a module/sub-module must be in the order above?

No, as it is a list of alternatives. Each time "data-def-stmt" is applied you can choose any one of the alternatives.

Lada

>> +1.  Isn't this exactly what a SHOULD statement means.  I.e. put in ascending order unless there is a good reason not to do so (e.g. as per Lada's examples), in which case that is fine.
>> 
>> Rob
>> 
>> 
>>>

---

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

> container, list, leaf-list, leaf, choice, case, anyxml, or anydata.

I think RFC 7950 is correct.  It says:

  The ABNF grammar defines the canonical order.

and the grammar allows mixing of container/list etc. (see also Lada's
email).

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 31 Jan 2017 09:48:31 +0100

> On 30 Jan 2017, at 12:38, Robert Wilton <[email-masked]> wrote:
> 
> Hi Andy, Lada,
> 

OK

> +1.  Isn't this exactly what a SHOULD statement means.  I.e. put in ascending order unless there is a good reason not to do so (e.g. as per Lada's examples), in which case that is fine.

If tools are supposed to issue a warning, and drafts to be flagged in Benoit's list, then it becomes a significant annoyance. How about this formulation:

The "enum" and "bit" statements SHOULD be ordered in a way that is appropriate for a given parameter, e.g., alphabetically or by numeric values or positions.

Lada

---

From: Robert Wilton <[email-masked]>
Date: Tue, 31 Jan 2017 09:48:29 +0000

> No, as it is a list of alternatives. Each time "data-def-stmt" is applied you can choose any one of the alternatives.
Ah, yes.  So given that the grammar is 7950 is correct, then presumably 
it is reasonable to reference it from 6087bis.

Rob

---

From: Andy Bierman <[email-masked]>
Date: Tue, 31 Jan 2017 20:21:25 -0800

Hi,

I updated the rfc6087bis draft and did not either of these 2 guidelines.

Andy

On Tue, Jan 31, 2017 at 1:48 AM, Robert Wilton <[email-masked]> wrote:

>>>>> IMO, this adds nothing to what's already stated in 7950. According to
>>>>> RFC 2119, SHOULD and RECOMMENDED mean the same.
>>>>>
>>>> think that it is buried with the ABNF, which won't necessarily be read by
>>>> all users of YANG.  Pulling it out in 6087bis doesn't seem to do any harm.
>>>>
>>>>
>>>>
>> No, as it is a list of alternatives. Each time "data-def-stmt" is applied
>> you can choose any one of the alternatives.
>>
> Ah, yes.  So given that the grammar is 7950 is correct, then presumably it
> is reasonable to reference it from 6087bis.
>
> Rob
>
>