Subject: [netconf] Usage examples for max-depth (rfc8526)

From: "Wisotzky, Sven (Nokia - DE/Stuttgart)" <[email-masked]>
Date: Thu, 14 Mar 2019 08:53:00 +0000

Unfortunately the info provided in RFC 8526 about the max-depth attribute is not very precise.
Is it fair to assume, that behavior is aligned with the RESTCONF "depth" attribute described in RFC 8040?

Let's use the following sample from chapter 3.1.1.3:
       <top xmlns="http://example.com/schema/1.2/config">
         <users>
           <user>
             <name>root</name>
             <type>superuser</type>
             <full-name>Charlie Root</full-name>
             <company-info>
               <dept>1</dept>
               <id>1</id>
             </company-info>
           </user>
           <!-- additional <user> elements appear here... -->
         </users>
       </top>

Example 1: no subtree filter is provided, max-depth=1
       <top xmlns="http://example.com/schema/1.2/config">
       </top>

Example 2: no subtree filter is provided, max-depth=2
       <top xmlns="http://example.com/schema/1.2/config">
         <users>
         </users>
       </top>
Assumption the container <users> would only be present in the result, if this container has any explicit children configuration. If there is no children config, it would not be part of the output.

Example 3: no subtree filter is provided, max-depth=3
       <top xmlns="http://example.com/schema/1.2/config">
         <users>
           <user>
           </user>
         </users>
       </top>
Somewhat interesting scenario. It provides the netconf client with a method to check, if a list contains any entries. So if the XML node <user> is contained, we would know that the list "user" has at least one entry. However, this XML output would not validate against the YANG model - because list-keys (user/name) are mandatory. In essence, that client requires to be flexible when parsing such result and cannot be restricted to YANG.

Example 4: no subtree filter is provided, max-depth=4
       <top xmlns="http://example.com/schema/1.2/config">
         <users>
           <user>
             <name>root</name>
             <type>superuser</type>
             <full-name>Charlie Root</full-name>
             <company-info>
             </company-info>
           </user>
           <!-- additional <user> elements appear here... -->
         </users>
       </top>
Similar to example 2, the container <company-info> would only be present, if this container has explicit children configuration.

Someone please to confirm, if those examples and assumptions being made are correct!

/wiso

---

From: Balázs Lengyel <[email-masked]>
Date: Mon, 18 Mar 2019 14:59:50 +0000

As a private opinion:

Providing a list without keys is kind of useless. IMHO keys should 
always be present if the list is allowed by depth. In my view the 
correct answer is:

               <name>Joe</name>
            </user>
            <user>
               <name>Bill</name>
            </user>
            <user>
               <name>Balazs</name>
            </user>
          </users>
        </top>

So even if the key name is strictly speaking on depth=4 it should be 
included in a level 3 get result.

regards Balazs

On 2019. 03. 14. 9:53, Wisotzky, Sven (Nokia - DE/Stuttgart) wrote:
> _______________________________________________
> netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>
-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909              email: [email-masked]

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 18 Mar 2019 17:58:51 +0000

Hi Sven,

Yes, I think that intention is to be consistent with the RESTCONF behaviour.  Although, there might be a slight bug in the example 3 on page 129 of RFC 8040; I would expect both "artist" and "song" to be represented as empty arrays rather than empty objects.

My take is, assuming top is a top level container:

Example 1: yes

Example 2: yes, but your assumption does not necessarily hold.  Section 7.5.7 of RFC 7950 allows non-presence container to be returned even if it does not contain any children, so I don't think that you can infer anything if it is present in the output.  If the container has presence then your assumption does hold.

Example 3: yes, that is what I would expect the output to be.

Example 4.  Same answer as for 2.

In terms of the expected behaviour then I think that the result should be equivalent to the server generating the full output for the request and then removing all nodes that are deeper than the depth parameter.  Obviously a server could implement it more efficiently than this.

Thanks,
Rob

-----Original Message-----
From: netconf <[email-masked]> On Behalf Of Wisotzky, Sven (Nokia - DE/Stuttgart)
Sent: 14 March 2019 08:53
To: [email-masked]
Subject: [netconf] Usage examples for max-depth (rfc8526)

/wiso

---

From: "Wisotzky, Sven (Nokia - DE/Stuttgart)" <[email-masked]>
Date: Tue, 19 Mar 2019 05:32:21 +0000

Hi Balázs,

I do agree, that having 3 empty <user> containers would somewhat useless. Originally I am looking for a simple (in-expensive) way to check, if a list has any elements. In your model, it might be rather simply by asking for max-depth=2. If <users/> is returned list is considered not empty, is <users/> is NOT returned list is considered empty.

However, I don’t think we can claim it for guaranteed that lists are always implemented as container of a single list. While now we could argue, that returning all list entries with just the list-keys is efficient enough - I still would be worried about huge lists, which potentially have 100k+ entries. Still in those cases, we fully rely on the performance of the NETCONF server and performance of the connection - while we might not even actually interested in the details of such list.

Key take-aways:
(1) It seems at least the definition in rfc8526 is not precise enough and leaves room for interpretation/implementation. This must be avoided, as any NETCONF/RESTCONF client depends on having a reliable interface to talk to. Therefore an action shall be taken, to make the RFC definition more precise by providing a more detailed descriptions and examples.
(2) There is a generic need to retrieve list details, without retrieving the entire list. It starts with the easy check, if a list contains entries or is empty. Taking this idea one step further would be, to ask how many entries a list currently has. I also remember there used to be IETF DRAFTS talking about meta-data - like when has a list updated the last time.

Might be good to have some follow-up discussion with the wider community, on how we want to have those 2 items addressed.

Cheers
/wiso

On 18.03.19, 16:00, "netconf on behalf of Balázs Lengyel" <[email-masked] on behalf of [email-masked]> wrote:

    As a private opinion:

    
    
    regards Balazs