Subject: [netmod] RPC input parameter definition order (uses augment)

From: Jernej Tuljak <[email-masked]>
Date: Fri, 1 Apr 2022 12:50:25 +0200

Hi,

RFC7950, 7.14.4. says:

    Input parameters are encoded as child XML elements to the rpc node's
    XML element, in the same order as they are defined within the "input"
    statement.

For the following model:

module b {
   namespace "b:uri";
   prefix b;

   grouping params {
     container params {
       leaf x {
         type string;
       }
     }
   }

   rpc foo {
     input {
       uses params {
         augment params {
           leaf y {
             type string;
           }
         }
       }
     }
   }
}

If both "leaf" data nodes are instantiated (XML encoding) as part of 
<rpc> for "foo", does <x> come before or after <y> (in document order)?

Jernej

---

From: Kent Watsen <[email-masked]>
Date: Fri, 1 Apr 2022 11:24:39 +0000

Hi Jernej,

> If both "leaf" data nodes are instantiated (XML encoding) as part of <rpc> for "foo", does <x> come before or after <y> (in document order)?

Augmented-in nodes come after other nodes. 

I’ve always wished there were a way to specify where they’re placed, for readability, but it’s too inconsequential to raise as an issue here. 

> Jernej

Kent

---

From: Andy Bierman <[email-masked]>
Date: Fri, 1 Apr 2022 06:49:36 -0700

> Augmented-in nodes come after other nodes.

Maybe this is an implementation convention, but the RFC says they are
encoded in any order.
https://datatracker.ietf.org/doc/html/rfc7950#section-7.17.2

I’ve always wished there were a way to specify where they’re placed, for
> readability, but it’s too inconsequential to raise as an issue here.

There is no canonical order defined for any schema nodes.
There is no order at all defined for top-level or augmenting schema nodes.

> Kent

Andy

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

---

From: Jernej Tuljak <[email-masked]>
Date: Mon, 4 Apr 2022 13:48:43 +0200

On 01/04/2022 15:49, Andy Bierman wrote:
>     > If both "leaf" data nodes are instantiated (XML encoding) as
>     part of <rpc> for "foo", does <x> come before or after <y> (in
>     document order)?
>

You are referring to this:

    When a node is augmented, the augmenting child nodes are encoded as
    subelements to the augmented node, in any order.

This implies interleaving of augmenting and non-augmenting child nodes 
within "input" parameters for XML encoding?

Jernej

>
>     I’ve always wished there were a way to specify where they’re
>     placed, for readability, but it’s too inconsequential to raise as
>     an issue here.
>
>

---

From: Andy Bierman <[email-masked]>
Date: Mon, 4 Apr 2022 08:16:38 -0700

> within "input" parameters for XML encoding?
There is no data node order defined except in 4 places:
  - rpc or action input (just the child nodes or all descendants?)
  - rpc or action output  (just the child nodes or all descendants?)
  - ordered by user applies to list and leaf-list entries
    (not the nodes within a list, just the list entries themselves)
  - list key leafs are encoded in key-stmt order, before other list child
nodes.
    This is true even if the list is affected by previous 3 rules (but this
is not specified)

It is not clear if the phrase "in any order" (appearing about a dozen times)
is in addition to these rules or instead of them.

What about an 'anyxml' or  'anydata' for a <config> node?
Since it is a terminal node, it could be interpreted that it is ordered,
but it is converted to regular nodes when applied to a datastore.

Andy

Jernej

---

From: Robert Varga <[email-masked]>
Date: Tue, 5 Apr 2022 00:34:08 +0200

> within "input" parameters for XML encoding?

Yes. There is no semantic difference in directly-defined on augmenting 
nodes, especially in 'uses/augment' case -- they share the same 
namespace, so at the document level (i.e. effective model) there is no 
difference between the two.

Any ordering should be treated as an implementation artifact. In 
particular this declaration:

rpc foo {
   grouping foo {
     container foo {
       leaf foo {
         type string;
       }
     }
   }

   input {
     uses foo {
       augment foo {
         leaf bar {
           type uint8;
         }
       }
     }
   }
}

is completely equivalent to:

rpc foo {
   input {
     container foo {
       leaf bar {
         type uint8;
       }
       leaf foo {
         type string;
       }
     }
   }
}

The presence of the intermediate grouping is a pure module-internal 
modeling detail. I believe introducing/removing the grouping is a 
non-breaking change as per RFC6020 (if memory serves right).

Regards,
Robert

---

From: Jernej Tuljak <[email-masked]>
Date: Tue, 5 Apr 2022 09:13:54 +0200

On 04/04/2022 17:16, Andy Bierman wrote:
>
>
> On Mon, Apr 4, 2022 at 4:48 AM Jernej Tuljak 
> <[email-masked]> wrote:
>
>>         > If both "leaf" data nodes are instantiated (XML encoding)
>>         as part of <rpc> for "foo", does <x> come before or after <y>
>>         (in document order)?
>>
>>     Maybe this is an implementation convention, but the RFC says they
>>     are encoded in any order.
>     This implies interleaving of augmenting and non-augmenting child
>     nodes within "input" parameters for XML encoding?
>
>
>   - list key leafs are encoded in key-stmt order, before other list 
> child nodes.
>     This is true even if the list is affected by previous 3 rules (but 
> this is not specified)

Additionally, there are interleaving rules for list and leaf-list entries.

    The XML elements representing
    list entries MAY be interleaved with elements for siblings of the
    list, unless the list defines RPC or action input or output
    parameters.

    The XML elements
    representing leaf-list entries MAY be interleaved with elements for
    siblings of the leaf-list, unless the leaf-list defines RPC or action
    input or output parameters.

Until augmentation comes along?

> is in addition to these rules or instead of them.

I'm not convinced of your interpretation of "in any order" in text you 
were originally referring to (and I later quoted). No matter how many 
times I read that, the "in any order" there only becomes relevant if 
there is more than one augmenting child present - to me, the intention 
behind that text was to handle multiple augments targeting the same 
node, not to introduce interleaving with non-augmenting children.

There should be text present in that section clarifying what that 
sentence means in contexts where order matters.

> but it is converted to regular nodes when applied to a datastore.

The way I see it, only the node representing the <config> node is an 
input/output parameter. The content is an opaque blob of data. No 
different to a leaf of type binary, which contains bytes of an XML document.

With such ambiguity in the RFC it would not be surprising if 
implementations chose to ignore these rules entirely and just accepted 
RPC payloads with arbitrary order of their content, even for the cases 
where things are somewhat clear. Or hope that all other implementations 
follow the same implementation convention.

Jernej

>>         placed, for readability, but it’s too inconsequential to
>>         raise as an issue here.
>>
>>

---

From: Jernej Tuljak <[email-masked]>
Date: Tue, 5 Apr 2022 09:14:58 +0200

On 05/04/2022 00:34, Robert Varga wrote:
>>>     > If both "leaf" data nodes are instantiated (XML encoding) as

Module updating rules state this:

    o  Any set of data definition nodes may be replaced with another set
       of syntactically and semantically equivalent nodes.  For example,
       a set of leafs may be replaced by a "uses" statement of a grouping
       with the same leafs.

and this:

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

Can you state that your second example may be rewritten into your first 
one while retaining semantic equivalence? For the second example, it is 
clear that XML encoding for that container imposes ordering on <bar> and 
<foo> (in that order), for the first, this is no longer true.

Jernej

---

From: Robert Varga <[email-masked]>
Date: Tue, 5 Apr 2022 11:17:49 +0200

> <foo> (in that order), for the first, this is no longer true.

I stand corrected, I forgot about the second statement and also the 
special-case of RPC input/output:

>    The container's child nodes are encoded as subelements to the
>    container element.  If the container defines RPC input or output
>    parameters, these subelements are encoded in the same order as they
>    are defined within the "container" statement.  Otherwise, the
>    subelements are encoded in any order.

Regards,
Robert