Subject: [netmod] Where can I insert new YANG substatements?

From: William Ivory <[email-masked]>
Date: Wed, 3 Feb 2016 08:58:51 +0000

Hi,

My colleagues and I are looking for clarification of the last point in Section 10 of YANG 1.0:

'   In statements that have any data definition statements as
   substatements, those data definition substatements MUST NOT be
   reordered.'

We understand that existing statements must not be reordered in a new revision of a YANG module, but we're not clear if new statements may be inserted between existing statements, or must always come at the 'end' of a list or container definition.  A specific example we're concerned with is where a grouping is used, and then later that grouping has an extra element added, but the new node could also be added directly.  Eg:

Container foo {
        Leaf A
        Uses grouping B;
        Leaf C
        Leaf D
}

Is it valid in a new revision of the module to do the following, or must the order be A, B, C, D, E?  What if grouping B has gained a new statement?

Container foo {
        Leaf A
        Uses grouping B;
        Leaf C
        Leaf E < ---- ADDED
        Leaf D
}

Thanks,

William

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 3 Feb 2016 10:19:28 +0100

Hi William,

> On 03 Feb 2016, at 09:58, William Ivory <[email-masked]> wrote:
> 
> Hi,
>  
> ‘   In statements that have any data definition statements as
>    reordered.’

This was already discussed:

https://mailarchive.ietf.org/arch/msg/netmod/CiVOMEDXfbQKKbgTXTznZh2HQQw

My understanding was that the paragraph you cite would be modified in 6020bis, but apparently it hasn't been so far. I don't see any reason for insisting on the order of sibling data node definitions in configuration and state data since in instance documents the order is arbitrary in both XML and JSON encoding.

>  
> We understand that existing statements must not be reordered in a new revision of a YANG module, but we’re not clear if new statements may be inserted between existing statements, or must always come at the ‘end’ of a list or container definition.  A specific example we’re concerned with is where a grouping is used, and then later that grouping has an extra element added, but the new node could also be added directly.  Eg:
>  
> Container foo {
>         Leaf A
>         Uses grouping B;
>         Leaf C
>         Leaf D 
> }
>  

I think this is allowed in any case.

Lada

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

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

---

From: William Ivory <[email-masked]>
Date: Wed, 3 Feb 2016 09:55:40 +0000

Hi Lada,

I was hoping for more than 'I think' and ' Hmm.  The rule is not clear.  In fact, one can argue that it is wrong:'.  Is anyone willing / able to give me a definitive answer?

Thanks,

William

-----Original Message-----
From: Ladislav Lhotka [mailto:[email-masked]] 
Sent: 03 February 2016 09:19
To: William Ivory <[email-masked]>
Cc: [email-masked]
Subject: Re: [netmod] Where can I insert new YANG substatements?

Hi William,

https://urldefense.proofpoint.com/v2/url?u=https-3A__mailarchive.ietf.org_arch_msg_netmod_CiVOMEDXfbQKKbgTXTznZh2HQQw&d=CwIFaQ&c=IL_XqQWOjubgfqINi2jTzg&r=GByLeg9jZvOv_AlgBo9uvdDrxizlOR7l_SnTXowyJU8&m=IVWnHPIm0qEHmxsw6Hhp_1xhdn2lIC4CSzMCsjh-zLo&s=SqU7w-muS4t_zhH19_1iyPLVl3tD24OUgJijkp4NX4E&e= 

Lada

> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netmod&d=CwIFaQ&c=IL_XqQWOjubgfqINi2jTzg&r=GByLeg9jZvOv_AlgBo9uvdDrxizlOR7l_SnTXowyJU8&m=IVWnHPIm0qEHmxsw6Hhp_1xhdn2lIC4CSzMCsjh-zLo&s=0jQV22VeCUg5PDxgGj0fih8or13yFSYEsMqK1ALagu8&e=

---

From: Andy Bierman <[email-masked]>
Date: Wed, 3 Feb 2016 03:56:17 -0800

On Wed, Feb 3, 2016 at 1:55 AM, William Ivory <[email-masked]> wrote:

> Hi Lada,
>
> I was hoping for more than 'I think' and ' Hmm.  The rule is not clear.
> In fact, one can argue that it is wrong:'.  Is anyone willing / able to
> give me a definitive answer?
>
> Thanks,
>
> William
>
> My understanding was that the paragraph you cite would be modified in
> 6020bis, but apparently it hasn't been so far. I don't see any reason for
> insisting on the order of sibling data node definitions in configuration
> and state data since in instance documents the order is arbitrary in both
> XML and JSON encoding.
>
>

I have also mentioned in the past that this MUST NOT needs to be changed
or at least clarified.

According to RFC 2119, "MUST NOT" is supposed to be used when harm
to inter-operability needs to be prevented. There are only 2 corner-cases
where YANG-stmt order matters
 - default-stmt for a leaf-list
 - auto-numbering for enum or bits

There are already update rules to prevent these statements from being
reordered,
so this MUST NOT is not needed at all.

>
> > We understand that existing statements must not be reordered in a new
> revision of a YANG module, but we’re not clear if new statements may be
> inserted between existing statements, or must always come at the ‘end’ of a
> list or container definition.  A specific example we’re concerned with is
> where a grouping is used, and then later that grouping has an extra element
> added, but the new node could also be added directly.  Eg:
> >
> > Container foo {
> >         Leaf A
> >         Uses grouping B;
> >         Leaf C
> >         Leaf D
> > }
> >
> > Is it valid in a new revision of the module to do the following, or must
> the order be A, B, C, D, E?  What if grouping B has gained a new statement?
> >
> > Container foo {
> >         Leaf A
> >         Uses grouping B;
> >         Leaf C
> >         Leaf E < ---- ADDED
> >         Leaf D
> > }
>

This is allowed.

It is also allowed to move objects to/from submodules and there is
no fixed order to submodules within a module.

This is also allowed, which has the same affect:

   container bar {
      uses foo;   /// <--- add leaf E after D, still reorders X
      leaf X{}
   }

> Lada

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 03 Feb 2016 18:06:15 +0100 (CET)

Hi,

William Ivory <[email-masked]> wrote:
> revision of a YANG module, but we're not clear if new statements may
> be inserted between existing statements, or must always come at the
> 'end' of a list or container definition.

They can be inserted anywhere.

As Lada pointed out, this should be clarified in 6020bis.  I will do:

OLD:

  In statements that have any data definition statements as
  substatements, those data definition substatements MUST NOT be
  reordered.

NEW:

  In statements that have any data definition statements as
  substatements, those data definition substatements MUST NOT be
  reordered.  If new data definition statements are added, they can be
  added anywhere between these substatement.

> A specific example we're
> concerned with is where a grouping is used, and then later that
> grouping has an extra element added, but the new node could also be
> added directly.  Eg:
> 
> Container foo {
>         Leaf A
>         Uses grouping B;
>         Leaf C
>         Leaf D
> }
> 
> Is it valid in a new revision of the module to do the following, or
> must the order be A, B, C, D, E?  What if grouping B has gained a new
> statement?
> 
> Container foo {
>         Leaf A
>         Uses grouping B;
>         Leaf C
>         Leaf E < ---- ADDED
>         Leaf D
> }

This is valid.

/martin

---

From: William Ivory <[email-masked]>
Date: Wed, 3 Feb 2016 17:22:01 +0000

Hi Martin,

Thanks - that looks good to me.

William

-----Original Message-----
From: Martin Bjorklund [mailto:[email-masked]] 
Sent: 03 February 2016 17:06
To: William Ivory <[email-masked]>
Cc: [email-masked]
Subject: Re: [netmod] Where can I insert new YANG substatements?

Hi,

OLD:

NEW:

This is valid.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Wed, 3 Feb 2016 09:32:39 -0800

>   added anywhere between these substatement.

This is not very good.
You should explain exactly what interoperability is lost if a data-def-stmt
changes relative order from 1 release to the next.  If it is a MUST NOT,
then this should obvious.  Given that list keys MUST be encoded first,
and XML and JSON allow reordering anyway, it is a completely
mystery to me why this CLR exists at all.

(BTW, it has no affect at all on default-stmt, bit-stmt, or enum-stmt,
the only 3 YANG statements where schema-order is actually relevant).

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 03 Feb 2016 19:45:51 +0100 (CET)

Andy Bierman <[email-masked]> wrote:
> changes relative order from 1 release to the next.

Note that this how YANG 1.0 works.

The reason for this rule is that the order does matter for rpc
input/output - they are encoded in XML in the order they are defined.

The rule could be limited to input/output, but groupings might be
used, so it would have to be input/output and groupings.

/martin

> If it is a MUST NOT,