[yang-doctors] List key model definition order and results w/ pyang/yanglint

[Ebben Aries <[e-mail]>]

Possibly bringing up a subject that may have been discussed before but
could not find anything on it so sending to the group.

RFC 6020 and 7950 both have the same wording on the subject around list
keys per

https://tools.ietf.org/html/rfc6020#section-7.8.2
https://tools.ietf.org/html/rfc7950#section-7.8.2

>From a model definition standpoint, there is nothing mandatory
surrounding that list keys be the first leaf definitions underneath.

>From a content encoding standpoint, the following XML Mapping Rules in
https://tools.ietf.org/html/rfc6020#section-7.8.5 do dictate an order
that the keys be defined before other subelements.  JSON obviously does
not utilize the same encoding technique.

   The list's key nodes are encoded as subelements to the list's
   identifier element, in the same order as they are defined within the
   "key" statement.

   The rest of the list's child nodes are encoded as subelements to the
   list element, after the keys.  If the list defines RPC input or
   output parameters, the subelements are encoded in the same order as
   they are defined within the "list" statement.  Otherwise, the
   subelements are encoded in any order.

Given the following simple example:

module test {
    namespace "http://test";
    prefix test;

    container foo {
        leaf bar {
            type string;
        }
        list car {
            key "far mar";

            leaf par {
                type string;
            }
            leaf far {
                type string;
            }
            leaf mar {
                type string;
            }
            leaf nar {
                type string;
            }
        }
    }
}

leaf 'par' here is defined before the 'far' and 'mar' keys, however if
we render out a sample-xml-skeleton with pyang, we do not take into
account the XML encoding rules defined in Section 7.8.5 and merely keep
the order as defined in the model.

$ pyang test.yang --strict -f sample-xml-skeleton
<?xml version='1.0' encoding='UTF-8'?>
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <foo xmlns="http://test">
    <bar />
    <car>
      <par />
      <far />
      <mar />
      <nar />
    </car>
  </foo>
</data>

With yanglint, given the following XML document

$ cat test.xml
<foo xmlns="http://test">
    <bar>BAR</bar>
    <car>
        <par>PAR</par>
        <far>FAR</far>
        <mar>MAR</mar>
        <nar>NAR</nar>
    </car>
</foo>

The rendered XML output will actually reorder the list keys to be first

$ yanglint -f xml test.yang test.xml
<foo xmlns="http://test">
  <bar>BAR</bar>
  <car>
    <far>FAR</far>
    <mar>MAR</mar>
    <par>PAR</par>
    <nar>NAR</nar>
  </car>
</foo>

Personally, from a BCP standpoint, defining list keys first eases
readability and want to solicit others thoughts on this (rather than
nested down in the list or via a grouping reference further down).
Generation to yin does not rearrange in either pyang or yanglint which
means any processing of yin would need to undergo some reordering
possibly depending on how it is absorbed.

For the JSON encoding case, there may be no strict ordering but
following a BCP where folks *should* send list keys before other
elements can ease implementation efforts in many cases.  It is also
likely that payloads will generally be constructed in the order in which
they are defined in the model.

So either I see making the definition of such either mandatory or at a
bare minimum pyang sample-xml-skeleton output to take into account
ordering list key leafs prior to other subelements.

Thx

/ebben