Subject: Gen-Art LC review: draft-ietf-netmod-yang-metadata-04

From: Robert Sparks <[email-masked]>
Date: Tue, 1 Mar 2016 15:51:49 -0600

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Document: draft-ietf-netmod-yang-metadata-04
Reviewer: Robert Sparks
Review Date: 1Mar2016
IETF LC End Date: 9Mar2016
IESG Telechat date: not yet scheduled

Summary: Ready with nits

1) I might be missing something obvious, but the introduction has two 
statements that don't seem aligned:

" Values of annotations are not limited to strings; any YANG built-in or 
derived type may be used for them"
and
"annotations are scalar values and cannot be further structured".

If I'm not missing something, that may be more of an open issue than a nit.

2) The shepherd writeup calls out the tension in figuring out whether to 
make this an extension or a new built-in statement. Please consider 
capturing the reasoning for the path you chose in the draft itself.

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 09 Mar 2016 18:04:08 +0100

Hi Robert,

thanks for the review, I apologize for replying late, please see my responses inline:

> "annotations are scalar values and cannot be further structured".

These two statements are not in conflict: YANG data types (built-in or
derived) apply to scalar values. 

> capturing the reasoning for the path you chose in the draft itself.

I will try, the main reason was that most people felt that introducing a
new built-in statement is too big a change for the upcoming maintenance
version of YANG (1.1) and YANG 2.0 is nowhere in sight.

Thanks, Lada

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Robert Sparks <[email-masked]>
Date: Thu, 10 Mar 2016 17:57:23 -0600

> derived) apply to scalar values.
I don't know what it means for a data type to apply to a value. Can you 
say that more simply?

I think this is just a language thing, and being precise in the text 
will get past it.

Are you saying all YANG data types (built-in or derived) have only 
scalar values?

If so, you could change the second point in the document to say
"Since annotations have only built-in or derived types, they can only 
have scalar values."

But then, placing the point under "This document deliberately adopts 
some restrictions" doesn't make sense, and I suggest restructuring the 
discussion to only call out the restrictions (which appears to be to not 
place annotations on lists or leaf-lists) below that sentence.

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 11 Mar 2016 10:32:10 +0100

> On 11 Mar 2016, at 00:57, Robert Sparks <[email-masked]> wrote:
> 
> 
> 
> I don't know what it means for a data type to apply to a value. Can you say that more simply?

Every leaf node definition must define the leaf's type - built-in or derived. Annotations can use exactly the same types. YANG types are analogical to what "datatype" means in W3C XML Schema or RELAX NG - it represents constraints for a *scalar* value (or text in XML terms). I think you are confusing categories of YANG data nodes (leaf, container, list, leaf-list, anyxml, anydata) with types (string, boolean, int8, etc.).

> 
> I think this is just a language thing, and being precise in the text will get past it.

The Terminology section now refers to definitions of "built-in type" and "derived type" in draft-ietf-netmod-rfc6020bis, and the latter document is a normative reference. So understanding these terms is a prerequisite for the present document. In my view, the formulations are quite precise, but I am open to suggestions for improvements.

> 
> Are you saying all YANG data types (built-in or derived) have only scalar values?

No, data types represent constraints on scalar values.

> "Since annotations have only built-in or derived types, they can only have scalar values."
> 
> But then, placing the point under "This document deliberately adopts some restrictions" doesn't make sense, and I suggest restructuring the discussion to only call out the restrictions (which appears to be to not place annotations on lists or leaf-lists) below that sentence.

The logic is this: it would be trivial to extend the mechanism of this document to allow for annotations being arbitrarily complex data trees with containers, lists, etc. It is also not difficult to imagine use cases where it would come handy. However, the WG consensus was that at his time we don't want to give up the convenience of XML attributes in the XML encoding, and that's why we adopted extra restrictions that mirror the restrictions of XML attributes. I believe the text in the Introduction captures this quite well:

   In the XML encoding, XML attributes are a natural instrument for
   attaching annotations to data node instances.  This document
   deliberately adopts some restrictions in order to remain compatible
   with the XML encoding of YANG data node instances and limitations of
   XML attributes.  Specifically,

   o  annotations are scalar values and cannot be further structured;

   o  annotations cannot be attached to a whole list or leaf-list
      instance, only to individual list or leaf-list entries.

If it turns out that structured annotations are needed, another document (or an update to this one) can introduce them, including appropriate XML encoding rules.

Thanks, Lada

---

From: tom p. <[email-masked]>
Date: Fri, 11 Mar 2016 11:15:28 +0000

Lada, Robert

The other angle from which this might be approached is that the I-D
already says

"   Using the "type" statement, a type is specified for the annotation
   value according to the same rules as for YANG "leaf" type. "

while rfc6020bis says

"   The "leaf" statement is used to define a scalar variable of a
   particular built-in or derived type."

so if you know your YANG off by heart, then you will know that
annotations must be scalar.  I agree that the text needs to be clearer.
Perhaps,
OLD
"   o  annotations are scalar values and cannot be further structured;"
NEW
"Annotations obey the same rules as for a YANG "leaf" type [rfc6020bis
s.7.6] and so are limited to scalar variables."

Tom Petch

----- Original Message -----
From: "Ladislav Lhotka" <[email-masked]>
To: "Robert Sparks" <[email-masked]>
Cc: "General Area Review Team" <[email-masked]>; <[email-masked]>;
<[email-masked]>; <[email-masked]>
Sent: Friday, March 11, 2016 9:32 AM

> I don't know what it means for a data type to apply to a value. Can
you say that more simply?

Every leaf node definition must define the leaf's type - built-in or
derived. Annotations can use exactly the same types. YANG types are
analogical to what "datatype" means in W3C XML Schema or RELAX NG - it
represents constraints for a *scalar* value (or text in XML terms). I
think you are confusing categories of YANG data nodes (leaf, container,
list, leaf-list, anyxml, anydata) with types (string, boolean, int8,
etc.).

will get past it.

The Terminology section now refers to definitions of "built-in type" and
"derived type" in draft-ietf-netmod-rfc6020bis, and the latter document
is a normative reference. So understanding these terms is a prerequisite
for the present document. In my view, the formulations are quite
precise, but I am open to suggestions for improvements.

scalar values?

have scalar values."

The logic is this: it would be trivial to extend the mechanism of this
document to allow for annotations being arbitrarily complex data trees
with containers, lists, etc. It is also not difficult to imagine use
cases where it would come handy. However, the WG consensus was that at
his time we don't want to give up the convenience of XML attributes in
the XML encoding, and that's why we adopted extra restrictions that
mirror the restrictions of XML attributes. I believe the text in the
Introduction captures this quite well:

If it turns out that structured annotations are needed, another document
(or an update to this one) can introduce them, including appropriate XML
encoding rules.

Thanks, Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 11 Mar 2016 13:58:26 +0100

> On 11 Mar 2016, at 12:15, tom p. <[email-masked]> wrote:
> 
> Lada, Robert
> 

This is again confusing, "leaf" is a data node, not type. But even then, there are some things that may be defined for leafs but not for annotations, such as a default value or "must" expression.

As you rightly said, 6020(bis) is quite clear: types only pertain to scalar values. I believe the problem is in carrying over the meaning that "type" has in programming languages (array or struct type) to YANG.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 11 Mar 2016 14:07:07 +0100

> s.7.6] and so are limited to scalar variables."

There is no 'leaf type' in YANG. YANG has leaf nodes in the schema
tree. An annotation is not a node in the schema tree. Perhaps
something like this:

  An annotation carries a single value. The type substatement, which
  must be present, takes as an argument the name of an existing
  built-in or derived type and the value of the annotation must match
  this type. See Section 7.4 of [RFC6020bis] for details.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 11 Mar 2016 16:04:45 +0100

> On 11 Mar 2016, at 14:07, Juergen Schoenwaelder <[email-masked]> wrote:
> 

Looks good, thanks. Robert, Tom, do you think this text is sufficient? 

Lada

---

From: Robert Sparks <[email-masked]>
Date: Fri, 11 Mar 2016 09:16:19 -0600

Yes, thanks.

---

From: tom p. <[email-masked]>
Date: Fri, 11 Mar 2016 16:39:54 +0000

----- Original Message -----
From: "Juergen Schoenwaelder" <[email-masked]>
Sent: Friday, March 11, 2016 1:07 PM

> tree. An annotation is not a node in the schema tree. Perhaps

Juergen

Well, I know, but I was quoting directly from yang-metadata-04 s.3,
namely

"Using the "type" statement, a type is specified for the annotation
   value according to the same rules as for YANG "leaf" type. "

which is why I gave a reference to s7.6 of RFC6020bis rather than s.7.4.

Perhaps change s.3 in addition to your change

OLD
   Using the "type" statement, a type is specified for the annotation
   value according to the same rules as for YANG "leaf" type.
NEW
   Using the "type" statement, a type is specified for the annotation
   value according to the same rules as for the type of a YANG
"leaf"[RFC6020bis s.7.6].

I do think that that mention of leaf is helpful - as you say, the WG
agreed to this restriction as opposed to allowing more complex
annotations and referencing "leaf" for me makes that clearer.

Tom Petch

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 11 Mar 2016 18:16:35 +0100

I assume 'An annotation carries a single value.' should be clear
enough. A reference to section 7.6 is actually misleading since
that section deals with many more things that are not applicable
to leafs. But I think we are already done with this.

/js

---

From: Jari Arkko <[email-masked]>
Date: Thu, 17 Mar 2016 08:54:51 +0000

Thanks, Robert and all.

I have balloted no-objection for this draft on tonights’s IESG telechat.

Jari