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" <lhotka(_at_)nic(_dot_)cz>
To: "Robert Sparks" <rjsparks(_at_)nostrum(_dot_)com>
Cc: "General Area Review Team" <gen-art(_at_)ietf(_dot_)org>;
<ietf(_at_)ietf(_dot_)org>;
<netmod(_at_)ietf(_dot_)org>;
<draft-ietf-netmod-yang-metadata(_dot_)all(_at_)ietf(_dot_)org>
Sent: Friday, March 11, 2016 9:32 AM
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