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

From: Martin Bjorklund <[email-masked]>
Date: Mon, 02 Dec 2019 09:39:31 +0100 (CET)

Hi,

"Rob Wilton (rwilton)" <[email-masked]> wrote:
> Hi,
> 
> Perhaps this has been debated to death, or there is already an
> agreement, but do we have an agreed consistent approach for
> naming/containing lists in YANG?
> 
> In particular:
> 
>   1.  Should the list be enclosed in its own container
>   (e.g. interfaces/interface)?

I don't think all lists should be "forced" into either having a
container or not having a container.  Sometimes it makes sense and
sometimes it is doesn't.  Proper structure and naming is an art...

One recommendation is to avoid top-level lists, hence "/interfaces".

>   2.  Should the name of the list be singular or plural?

Singular!

>   3.  Should leaf-lists be treated similarly?

Singluar name, but enclosing leaf-lists in containers are rarely
useful.

>   4.  What if the list is a top level YANG node, does it get put into a
>   container in that scenario (e.g. network-instances/network-instance)?

Yes.

> I think that it would be good if we can have a consistent approach
> during reviews, perhaps folding into a future update of RFC 8407.
> 
> Looking at a couple of the recent models in RFCs, would seem to
> suggest:
> 
>   1.  Top-level data nodes should probably always be containers
>   2.  Lists don't need to be enclosed in a container (and should not be
>   top-level data-nodes).
>   3.  Names of lists and leaf-lists should be singular not plural.
> 
> Does that align with other folk's opinions?

Yes.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 02 Dec 2019 13:06:30 +0100

> sometimes it is doesn't.  Proper structure and naming is an art...

I agree but it is also worth noting that in XML representation (unlike JSON and
CBOR) list instances may get interleaved with instances of other data nodes, if
there is no enclosing container.

Lada

> _______________________________________________
> yang-doctors mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors
-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Tue, 3 Dec 2019 11:48:50 +0000

> -----Original Message-----
> From: yang-doctors <[email-masked]> On Behalf Of Ladislav
> Lhotka
> Sent: 02 December 2019 12:07
> To: [email-masked]
> Subject: Re: [yang-doctors] Consistency for naming lists and leaf-lists
> 
> CBOR) list instances may get interleaved with instances of other data
> nodes, if there is no enclosing container.

I don't that I'm trying to impose a hard and fast rule, but I would like a default position to strive for more consistency between YANG models.

Other than the case that the list would otherwise sit at the top level of a model, where it is better to have a single, or very small number of, root containers to contain all of the module's data nodes, then in what cases does it make sense to specifically add a container only around a list?

E.g. I would think that the XML encoding issue is either a generic issue that applies to all lists or none.  Why would it only be a consideration for some lists?

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

Thanks,
Rob

---

From: Kent Watsen <[email-masked]>
Date: Tue, 3 Dec 2019 15:17:24 +0000

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

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 03 Dec 2019 16:45:29 +0100 (CET)

Hi,

Kent Watsen <[email-masked]> wrote:
> 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 think that NP-containers should be used when they make sense from a
modelling pow, i.e., to provide structure to the nodes.  In most cases
such containers are not needed.  I do not agree that it is a good idea
to put a surrounding container on *all* lists just for the sake of it
(and eventually I am going to send comments re this and other things
like naming in your drafts, but not until we have agreement on the
basics).

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

I know it is common that REST apis are structured like this.  But a
YANG model is not a defintion for a REST interface; rather, RESTCONF
is one of many ways to access data modelled in YANG.

A good structure, just like good names, matter, even though we discuss
programmatic interfaces.

/martin

> 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):
> 
> 	 	GET
> 	 	/widgets/widget?limit=2&offset=3?sort=name?where='foo==bar'
> 
> 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

---

From: Andy Bierman <[email-masked]>
Date: Tue, 3 Dec 2019 08:08:20 -0800

> A good structure, just like good names, matter, even though we discuss

I agree with Martin about designing for RESTCONF when YANG is used for
several protocols.
(E.g. extra containers could mean extra keywords in the CLI)

A parent container does solve some protocol deficiencies in NETCONF and
RESTCONF
but we should resist strict CLRs and decide each case on its merits.

I am far more concerned about the style of organizing and publishing
groupings instead of accessible objects.
Just try implementing YANG Push/SN and you will see what I mean. The same
groupings used in different
places have different implementation details.  Most of the details are not
explained at all in the YANG object because the
grouping descriptions are intended to be context independent.  The
descriptions in "uses" subtrees in each context
are terse or non-existent.  Perhaps developers will make the same
implementation decisions. Perhaps not.
There are 100s of details spread out in the RFCs outside the YANG objects,
which makes sense for this
protocol and context independent approach, but makes development much more
complex.

> /martin
Andy

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Tue, 3 Dec 2019 16:55:11 +0000

Hi Kent,

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

Hi Rob,

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

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

                              POST /widgets

Kent