Re: [yang-doctors] Consistency for naming lists and leaf-lists

["Rob Wilton (rwilton)" <[e-mail]>]

Hi Kent,

From: Kent Watsen <[e-mail]>
Sent: 03 December 2019 15:17
To: Rob Wilton (rwilton) <[e-mail]>
Cc: Ladislav Lhotka <[e-mail]>; [e-mail]
Subject: Re: [yang-doctors] Consistency for naming lists and leaf-lists

Hi Rob,


Can't we just say that lists SHOULD NOT be put in their own containers to wrap the list?

If we were to pick a default stance, though I'm hesitant to think we should, I'd recommend the opposite, that containers SHOULD be used to wrap lists (and this strategy is used in all the models in the drafts I'm authoring).
FWIW, this is exactly why I think that we need a default stance.  The YANG models that IETF ends up standardizing are going to end up looking different and inconsistent depending on which YANG Doctor is doing the review.


I feel that this is conceptually more accurate.  That is, what we call a "list" is really a list-element, hence why it should have  singular name.  A wrapping-container, having a plural name, gives it the appearance of it being a collection at first glance (e.g., "/widget" vs. "/widgets/widget").

I don’t think that a YANG list as a list element, I think of it as the thing that represents the entire list (e.g. as it is encoded in CBOR/JSON).  Unfortunately, the different encodings (XML vs JSON/CBOR) end up with different representations on the wire, which probably doesn’t help.  I also think that avoiding unnecessary containers is the better approach.

If we were starting from scratch, with just the JSON/CBOR encodings, or a different XML encoding for lists, then I would have preferred naming the lists in the plural tense, just as I would normally name maps/lists/collections.  And there is part of me that thinks that using plurals might be the right approach going forward … although I suspect that Martin will disagree 😉

But for me, I think that the number one thing is that we are consistent, at least in the mainline case.

Thanks,
Rob



In REST APIs, clients create new list-elements by POST-ing to the parent resource, which acts as the list, supporting query options for sorting, filtering, searching, and pagination.  While it is possible to have heterogeneous contents (i.e., using media-types), it's most common for the contents to be homogeneous.  Any search for "REST API collection best practice" shows this.

The issue we're having is what might be called an "impedance mismatch".  In YANG, the list-element is the "list", but the parent node is rightfully the "collection".

Notably, https://tools.ietf.org/html/draft-ietf-netconf-restconf-collection<https://tools.ietf.org/html/draft-ietf-netconf-restconf-collection-00> effectively bucks REST API best practice, targeting the collection-oriented operations to the "list element" resource.  Accordingly, this resulting RESTCONF API is both asymmetric and different than most other REST APIs.  For example (simplified for brevity):

               To insert a new widget into the collection:

                              POST /widgets

               To get widgets in the collection:

                              GET /widgets/widget?limit=2&offset=3?sort=name?where='foo==bar'

               (both are "collection" operations, but act on different resources)

It is understandable why the "restconf-collection" draft takes the approach it does, it being the logical result of YANG allowing a container to having more than one 'list' descendant.  But, if we were ever to pick that draft up again, or perhaps as part of YANG-next, we could define a "collection" annotation for containers (or a "collection" statement) that would: 1) signal that the container contains exactly one list and 2) allow the list-operations to be targeted to the container resource.

In the meanwhile, while waiting for the "collections" work to be picked up again, I feel that the YANG best practice, if anything, should be to mimic this structure (a container wrapping each list).

Kent