Hi Martin,
Thanks for engaging quickly.
[I removed the resolved entries]
Hi Benoit,
Benoit Claise <[email protected]> wrote:
Dear all,
Here is part 1 of my AD review.
I found this useful:
http://tools.ietf.org/rfcdiff/rfcdiff.pyht?url1=http://www.ietf.org/rfc/rfc6020.txt&url2=http://www.ietf.org/id/draft-ietf-netmod-rfc6020bis-11.txt
- Do we want to mention RESTCONF in the abstract? From the new charter:
The NETMOD working group has defined the data modeling language
YANG, which can be used to specify network management data models
that are transported over such protocols as NETCONF and RESTCONF.
OLD:
YANG is a data modeling language used to model configuration data,
state data, remote procedure calls, and notifications for network
management protocols like the Network Configuration Protocol
(NETCONF).
NEW:
YANG is a data modeling language used to model configuration data,
state data, remote procedure calls, and notifications for network
management protocols transported over such protocols as Network
Configuration Protocol (NETCONF) and RESTCONF. This document specifies
the YANG mappings to NETCONF.
The first paragraph in the introduction mentions other protocols;
RESCTONF and CoMI. My personal opinion is that this is sufficient,
but I'd like to hear what others think.
The current abstract doesn't even mention the mapping to NETCONF.
Have we made an analysis of the 38 RFC-produced YANG modules? Any
facing issues with 1.1 compilation?
I have tested to put "yang-version 1.1;" into all RFC-published
modules, and then ran pyang on them w/o any issues.
Great.
- Section 1.1
Since this document introduces the NETCONF mapping, the protocol
change must be included in section 1.1
Example: no NETCONF capability exchange in YANG 1.1, we use
exclusively the YANG library
Any other ones?
And this one?
- Section 3
o anydata: A data node that can contain an unknown set of nodes that
can be modelled by YANG.
NEW
o anydata: A data node that can contain an unknown set of nodes that
can be modelled by YANG, except anyxml, but for which the data
model is not known at module design time.
Ok, but I'd say:
NEW:
o anydata: A data node that can contain an unknown set of nodes that
can be modelled by YANG, except anyxml.
This is just a summary; the details are to be found in later sections.
Sure.
- Terminology:
The following terms are defined in [RFC6241
<https://tools.ietf.org/html/rfc6241>]:
...
o configuration datastore: a configuration datastore is an
instantiated data tree with configuration data
o datastore: an instantiated data tree
RFC6241 has different definition for "configuration datastore" and
"datastore".
I would just provide the pointer to the RFC 6241 definitions.
If you intend to provide an adapted definition for the YANG mappings,
then you should say so.
How about:
OLD:
o configuration datastore: a configuration datastore is an
instantiated data tree with configuration data
o datastore: an instantiated data tree
NEW:
o configuration datastore: When modelled with YANG, a configuration
datastore is an instantiated data tree with configuration data
o datastore: When modelled with YANG, an instantiated data tree
This issue is with "The following terms are defined in [RFC6241]", but
you re-define those terms.
So give a warning about the redefinition to the readers.
- Section 4.1
YANG models can describe constraints to be enforced on the data,
restricting the appearance or value of nodes based on the presence or
value of other nodes in the hierarchy.
I was looking for an example of appearance.
NEW?
YANG models can describe constraints to be enforced on the data,
restricting the appearance (for example, with the "when" statement)
or value of nodes based on the presence or value of other nodes in
the hierarchy.
This is very early in the document, and the text tries to give a very
high level function overview. I am not sure that mentioning "when" at
this time actually helps a first time reader.
The first time I read this, I was wondering how YANG data models can
describe constraints on HOW data appear, while you wanted to express
WHETHER a data appear. Maybe "when" is not the best way to help the
first time user, but something is needed.
I would prefer to
leave it as it is.
container-stmt = container-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt]
*if-feature-stmt
*must-stmt
[presence-stmt
<https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis-11#ref-presence-stmt>]
[config-stmt]
[status-stmt]
[description-stmt]
[reference-stmt]
*(typedef-stmt / grouping-stmt)
*data-def-stmt
*action-stmt
*notification-stmt
"}") stmtsep
- Examples
I guess that no examples are supposed to compile, right?
Please add a sentence saying so.
I honestly does not think that this is an issue, but how about this:
NEW:
3.1. A Note on Examples
Throughout this document there are many examples of YANG statements.
These examples are supposed to illustrate certain features, and are
not supposed to be complete, valid YANG modules.
Sure.
- Section 5.6.4
If a server implements a module A that imports a module B, and A uses
any node from B in an "augment" or "path" statement that the server
supports, then the server MUST implement a revision of module B that
has these nodes defined. This is regardless of if module B is
imported by revision or not.
"imported by revision or not" I'm, confused because I read the
document in sequence.
From 5.1 and 5.1.1, it doesn't look like we have two options (import
by revision or not)
And the example shows the two possibilities:
import b {
revision-date 2015-01-01;
}
import c;
I found my answer in section 7.1.5:
When the optional "revision-date" substatement is present, any
typedef, grouping, extension, feature, and identity referenced by
definitions in the local module are taken from the specified revision
of the imported module. It is an error if the specified revision of
the imported module does not exist. If no "revision-date"
substatement is present, it is undefined from which revision of the
module they are taken.
You should write a sentence or two (imported by revision or not) about
in section 5.1 or 5.1.1
OLD:
Published modules evolve independently over time. In order to allow
for this evolution, modules need to be imported using specific
revisions. When a module is written, it uses the current revisions
of other modules, based on what is available at the time.
NEW:
Published modules evolve independently over time. In order to allow
for this evolution, modules can be imported using specific revisions.
When a module is written, it can import the current revisions of
other modules, based on what is available at the time.
And then a new paragraph last in the same section (5.1.1):
NEW:
If a module is not imported with a specific revision, it is undefined
which excat revision is used.
Yes.
- section 5.6.4
A server MUST NOT implement more than one revision of a module.
You should add that the server may contain more than one version for
import reasons.
This would be in line with
https://tools.ietf.org/html/draft-ietf-netconf-yang-library-05
This mandatory list contains one entry for each YANG data model
module supported by the server. There MUST be an entry in this list
for each revision of each YANG module that is used by the server. It
is possible for multiple revisions of the same module to be imported,
in addition to an entry for the revision that is implemented by the
server.
I started to write some text to address this issue, but it felt out of
place. This section is about modules that are implemented. Other
modules can be listed according to yang-library; but that is a
yang-library issue, not YANG 1.1.
Not YANG 1.1 but NETCONF/YANG 1.1
So I prefer to leave this section
as it is.
Regards, Benoit
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
