Subject: [netmod] Benjamin Kaduk's No Objection on draft-ietf-netmod-yang-data-ext-04: (with COMMENT)

From: Benjamin Kaduk via Datatracker <[email-masked]>
Date: Tue, 03 Dec 2019 10:46:12 -0800

Benjamin Kaduk has entered the following ballot position for
draft-ietf-netmod-yang-data-ext-04: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-data-ext/

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Section 1

   The "yang-data" extension from [RFC8040] has been copied here,
   renamed to "structure", and updated to be more flexible.  There is no

The Gen-Art reviewer had a good comment on this that should be acted
upon.

Section 2

   This does not mean a YANG data structure has to be used as a top-
   level protocol message or other top-level data structure.

I was confused by this until I got through Section 4, which (I think!)
clarified that I need a top-level extension directive to "declare the
named structure", but this is saying that once the structure is
declared, it can be placed anywhere in the tree as a "node of structure
type".  Perhaps we could add a few words here to clarify, e.g., "YANG
data structure, once defined," or "A YANG data structure can be used as
any other data type, in the rest of the module"?

Section 3

Do we need to say anything about how the child <node>s under
structure/augment-structure get printed?  (I assume they get the same
handling as for the datastore tree, but could be wrong.)

   The new sections, including spaces conventions is:

       structure <structure-name>:

(I see four spaces between the column the paragraph starts in and the
column the "structure" keyword starts in, not two.)

   [augment-structure]
   [...]
             The sub-statements of this extension MUST follow the ABNF
          rules below, where the rules are defined in RFC 7950:

            [status-stmt]
            [description-stmt]
            [reference-stmt]
            1*(data-def-stmt / case-stmt)

Comparing to RFC 7950's augment-stmt, we see that when-stmt and
if-feature-stmt are not present; would those be used externally to the
augment-structure declaration if needed?

Section 6

I might consider adding a note that the data being modelled might have
its own security considerations, but there's a pretty good case that
this is already covered in RFC 7950 and thus would be redundant here.

Appendix A.1

Using last+first as the only naming options (and the list keys) is
perhaps a bit unfortunate, given, e.g.,
https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/
(which has been popularized several times on varous social-media sites
over the years).
I suppose it still suffices for the purposes of this example, though.

Appendix A.3, A.4

As Alexey notes, maybe have two address entries in the example so that the reader sees
the encoding of the list structure?

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 04 Dec 2019 10:35:10 +0100 (CET)

Hi,

> https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-data-ext/

Yes. This is now changed to:

  This document defines a new YANG extension statement called
  "structure", which is similar to but more flexible than the
  "yang-data" extension from [RFC8040].

> type".

It means that once a structure is defined, we don't put any limitations
on how / where it is used.  It might be used to define some kind of
message that is used on its own, or it might be used to define a
structure that can be nested within some other data.  

An example of the latter is given in A.5.

> Perhaps we could add a few words here to clarify, e.g., "YANG

Yes, the former is better.  The sentence now reads:

  This does not mean a YANG data structure, once defined, has to be
  used as a top-level protocol message or other top-level data
  structure.

> handling as for the datastore tree, but could be wrong.)

They do.  Perhaps we can add:

   Nodes in YANG data structures are printed according to the rules
   defined in section 2.6 in [RFC8340].

> column the "structure" keyword starts in, not two.)

Thanks, fixed.

> augment-structure declaration if needed?

I will discuss this with my co-author and get back.  It might be an
oversight.

> this is already covered in RFC 7950 and thus would be redundant here.

Yes I think that since we specifically refer to the text in 7950 we
shouldn't just repeat that text.  I guess we could repeat the text
from 7950 and remove the reference, but I think I would prefer to keep
the ref.

> I suppose it still suffices for the purposes of this example, though.

I was going to suggest to use a single key "name", but that would
break his issues 1-4...  So hopefully the current list is ok; it is
just an example.

> the encoding of the list structure?

Ok, it doesn't hurt to add it, although I don't think that this
document is the right place to show examples of standard YANG encoding
rules.  I'll add one more address.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 05 Dec 2019 09:01:49 +0100 (CET)

Hi,

See one more reply inline.

> I will discuss this with my co-author and get back.  It might be an

If you need "if-feature" or "when" in this situation you can put it on
the nodes inside the "augment-structure".  For example, instead of:

  augment-structure ... {
    if-feature x;
    container y;
  }

you would do:

  augment-structure ... {
    container y {
      if-feature x;
    }
  }

and similar for "when".

/martin