On 11 Mar 2016, at 00:57, Robert Sparks <rjsparks(_at_)nostrum(_dot_)com>
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 <rjsparks(_at_)nostrum(_dot_)com> 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