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

[Kent Watsen <[e-mail]>]

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).

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").

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