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

[Ladislav Lhotka <[e-mail]>]

> On 11 Mar 2016, at 00:57, Robert Sparks <[e-mail]> wrote:
> 
> 
> 
> On 3/9/16 11:04 AM, Ladislav Lhotka wrote:
>> Hi Robert,
>> 
>> thanks for the review, I apologize for replying late, please see my responses inline:
>> 
>> Robert Sparks <[e-mail]> writes:
>> 
>>> 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".
>> These two statements are not in conflict: YANG data types (built-in or
>> 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?

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.

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

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

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