Subject: [netmod] AD review of draft-ietf-netmod-rfc6087bis-16 Part 1

From: Benoit Claise <[email-masked]>
Date: Thu, 25 Jan 2018 12:20:11 +0100

Dear all,

Thank you for this important document.
I've been spending quite some time trying to relay feedback seen on 
multiple fronts.
This is part 1 of the review, till section 4.21

-

    This document defines a set of usage guidelines for Standards Track
    documents containing [RFC7950 <https://tools.ietf.org/html/rfc7950>] data models.

This is not inline with:
    This section contains the module(s) defined by the specification.
    These modules SHOULD be written using the YANG 1.1 [RFC7950 <https://tools.ietf.org/html/rfc7950>] syntax.
    YANG 1.0 [RFC6020 <https://tools.ietf.org/html/rfc6020>] syntax MAY be used if no YANG 1.1 constructs or
    semantics are needed in the module.

So it should be changed to
    This document defines a set of usage guidelines for Standards Track
    documents containing YANG 1.1 [RFC7950 <https://tools.ietf.org/html/rfc7950>] and YANG 1.0 [RFC6020] data models.

Similarly in section 4
OLD:
    
    Modules in IETF Standards Track specifications MUST comply with all
    syntactic and semantic requirements of YANG [RFC7950 <https://tools.ietf.org/html/rfc7950>].

NEW:
    Modules in IETF Standards Track specifications MUST comply with all
    syntactic and semantic requirements of YANG 1.1 [RFC7950 <https://tools.ietf.org/html/rfc7950>]. See the exception
    for YANG 1.0 in section 3.6

Note that I tried to add some new text around the following sentence but that paragraph became clumsy.
    Alternatively,
    if YANG 1.0 is used, then Modules in IETF Standards Track specifications
    MUST comply with all syntactic and semantic requirements of YANG 1.0 [RFC6020].

Finally, in section 3.6, I would add a sentence to this paragraph
    This section contains the module(s) defined by the specification.
    These modules SHOULD be written using the YANG 1.1 [RFC7950 <https://tools.ietf.org/html/rfc7950>] syntax.
    YANG 1.0 [RFC6020 <https://tools.ietf.org/html/rfc6020>] syntax MAY be used if no YANG 1.1 constructs or
    semantics are needed in the module.

The sentence such as:
    if any the imported YANG modules is based on YANG 1.1, the main YANG
    module MUST also be written in YANG 1.1.

  - section 3, editorial:
    There are three usage scenarios for YANG that can appear in an
    Internet-Draft or RFC:

    o  normative module or submodule

    o  example module or submodule

    o  example YANG fragment not part of any module or submodule

    The guidelines in this document refer mainly to a normative_complete_
    module or submodule, but may be applicable to example modules and
    YANG fragments as well.

Either add "complete" to "o  normative module or submodule)" and be consistent throughout the document,
or remove it from the last sentence.

- section 3.2

    The "<CODE BEGINS>" tag SHOULD be followed by a string identifying
    the file name specified inSection 5.2 of [RFC7950] <https://tools.ietf.org/html/rfc7950#section-5.2>.  The name string
    form that includes the revision-date SHOULD be used.  The following
    example is for the '2010-01-18' revision of the 'ietf-foo' module:

    <CODE BEGINS> file "[email-masked]"

I would add that both revision versions (on the <CODE BEGINS> and in the module) MUST match.
I ran into all sort of tooling issues because of such discrepancies.

- section 3.2.1
Add "see section 4.9 regarding the namespace guidelines for example modules"

- The following in paragraph in section 3.3 seems misplaced.

        If YANG tree diagrams are used, then a normative reference to the
        YANG tree diagrams specification MUST be provided for each diagram.
        (Refer to the example in the next section.)

It should be in section 3.4.
Btw, no need to have the specifications for each diagram!
Also, we want to add some guidelines on how to reference the tree 
diagram convention
For ex: no need to copy over the conventions
Basically, we just need: 
https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03#section-1.3

PROPOSAL (replacing the previous paragraph)

        If YANG tree diagrams are used, then a normative reference to the
        YANG tree diagrams specification MUST be provided. As an example guideline
        (from https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03#section-1.3),
        here is a subsection in the terminology section

        Tree Diagrams

        Tree diagrams used in this document follow the notation defined in
        [I-D.ietf-netmod-yang-tree-diagrams
    <https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03#ref-I-D.ietf-netmod-yang-tree-diagrams>].

- section 3.5
You should add a good example to illustrate the second paragraph (Based 
on some previous feedback, YANG module designer wants to work from examples)
I would suggest to add 
https://tools.ietf.org/html/draft-ietf-netmod-rfc8022bis-09#section-2.3

- section 3.6, editorial
OLD:

   Note that all YANG statements within a YANG module are considered
    normative, if the module itself is considered normative, and not an
    example module.
NEW:

   Note that all YANG statements within a YANG module are considered
    normative, if the module itself is considered normative, and not an
    example module or a example YANG fragment.

- section 3.6

    Example YANG modules MUST NOT contain any normative text, including
    any reserved words from [RFC2119 <https://tools.ietf.org/html/rfc2119>].

I guess it applies also to the "example YANG fragments"

- section 3.10
Mention yanglint.
yanglint validates xpath, while pyang doesn't.

- section 3.11
You might consider the addition of xym https://github.com/xym-tool/xym

- section 3.12
mention that the examples MUST be validated.
Pointing to the tool would be a welcome addition.

- section 4.6.x
You should really mention a common mistake about the missing derived-from-or-self(), flagged in many YANG doctor reviews::
  
You should explain the applicability: identity augmentation.

- section 4.7 "Lifecycle Management"
     The status statement MUST be present if its value is 'deprecated' or
    'obsolete'.

I've been confused for a little, thinking this section was about the IETF document lifecyle management and the obsolete document tag.
Proposal: "Objects Lifecycle Management" or "YANG Objects Lifecycle Management"
     The YANG objects status statement MUST be present if its value is 'deprecated' or
    'obsolete'.

- section 4.8
    The contact statement MUST be present.  If the module is contained in
    a document intended for Standards Track status, then the working
    group web and mailing information MUST be present, and the main
    document author or editor contact information SHOULD be present.  If
    additional authors or editors exist, their contact information MAY be
    present.

I would add: No need to include the WG chair contacts.

- section 4.10

        The separation of configuration data and operational state SHOULD be
        considered carefully.  It is sometimes useful to define separate top-
        level containers for configuration and non-configuration data.  For
        some existing top-level data nodes, configuration data was not in
        scope, so only one container representing operational state was
        created.

What about NMDA?
This section is not inline with 4.23.3
Btw, in case a YANG supports NMDA , RFC6087bis should include the guideline is that it must be clearly mentioned.
The example of the abstract in https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03 could be mentioned.
    The YANG model in this document conforms to the Network Management
    Datastore Architecture defined in I-D.ietf-netmod-revised-datastores.

In the same section about "top-level data definitions", any guidelines in connection with https://datatracker.ietf.org/doc/draft-ietf-rtgwg-lne-model/ and schema mount?
Too early?

In section 4.23, add the [I-D.ietf-netmod-revised-datastores 
<https://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-16#ref-I-D.ietf-netmod-revised-datastores>] reference next to NMDA
In section 4.23.3
OLD:
(b) For published models, the model should be republished with an
    NMDA-compatible structure, deprecating non-NMDA constructs.  For
    example, the "ietf-interfaces" model in [RFC7223 <https://tools.ietf.org/html/rfc7223>] will be
    restructured as an NMDA-compatible model.

NEW:
(b) For published models, the model should be republished with an
    NMDA-compatible structure, deprecating non-NMDA constructs.  For
    example, the "ietf-interfaces" model in [RFC7223 <https://tools.ietf.org/html/rfc7223>] has been
    restructured as an NMDA-compatible model in [RFC7223bis].

I believe [I-D.ietf-netmod-revised-datastores] should a normative reference

- section 4.14.2

Something wrong with:
    -top-level siblings are not ordered -top-level siblings not are not
    static, and depends on the modules that are loaded

- section 4.17
Discussing with YANG doctors that a feature-per-leaf is most likely the wrong approach, Jürgen came up with this.

OLD

    The YANG "feature" statement is used to define a label for a set of
    optional functionality within a module.  The "if-feature" statement
    is used in the YANG statements associated with a feature.

    The set of YANG features available in a module should be considered
    carefully.  The description-stmt within a feature-stmt MUST specify
    any interactions with other features.

    If there is a large set of objects...

NEW

    The YANG "feature" statement is used to define a label for a set of
    optional functionality within a module.  The "if-feature" statement
    is used in the YANG statements associated with a feature.  The
    description-stmt within a feature-stmt MUST specify any
    interactions with other features.

    The set of YANG features defined in a module should be considered
    carefully. Very fine granular features increase interoperability
    complexity and should be avoided. A likely misuse of the feature
    mechanism is the tagging of individual leafs (e.g., counters) with
    separate features.

    If there is a large set of objects...

back to section 4.5
    If a data definition is optional, depending on server support for a
    NETCONF or RESTCONF protocol capability, then a YANG 'feature'
    statement SHOULD be defined to indicate that the NETCONF or RESTCONF
    capability is supported within the data model.

NEW:
     If a data definition is optional which depends on server support then
     a YANG 'feature' statement SHOULD be defined.  The defined 'feature'
     SHOULD then be used in the conditional 'if-feature' statement
     referencing the optional data definition.

This is currently under discussion with the YANG doctors.

Regards, Benoit

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 25 Jan 2018 12:59:41 +0100

>        here is a subsection in the terminology section

The current practice is that the tree diagrams reference is an
informative reference and not a normative reference.

/js

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

---

From: Benoit Claise <[email-masked]>
Date: Thu, 25 Jan 2018 13:20:30 +0100

> informative reference and not a normative reference.
Good catch Jürgen.

Regards, Benoit

---

From: Kent Watsen <[email-masked]>
Date: Thu, 25 Jan 2018 12:45:12 +0000

I see a lot of suggestions to reference other drafts as examples.  I would discourage doing that.  I recommend this draft clearly stating the desire, including its own examples if needed.

Regarding referencing the tree-diagrams draft, I don't agree that having a "Tree Diagrams" section in the Introduction is better than an inline reference where used:
1) the term "tree diagram" is not anywhere defined
2) sections having tree diagrams have to reference the section in the Introduction, and why reference the Intro section when it's just as easy to reference the draft?
3) it makes the Introduction and Table of Contents unnecessarily busy

Kent // contributor

On 1/25/18, 6:20 AM, "netmod on behalf of Benoit Claise" <[email-masked]<mailto:[email-masked]> on behalf of [email-masked]<mailto:[email-masked]>> wrote:

Dear all,

Thank you for this important document.
I've been spending quite some time trying to relay feedback seen on multiple fronts.
This is part 1 of the review, till section 4.21

-

   documents containing [RFC7950<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] data models.

This is not inline with:

   These modules SHOULD be written using the YANG 1.1 [RFC7950<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] syntax.

   YANG 1.0 [RFC6020<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc6020&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=L8LZohUWZQHgCc69tSH78w3mmeBF7ZpEaYGfDPYf5-8&e=>] syntax MAY be used if no YANG 1.1 constructs or

   documents containing YANG 1.1 [RFC7950<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] and YANG 1.0 [RFC6020] data models.

Similarly in section 4

OLD:

   syntactic and semantic requirements of YANG [RFC7950<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>].

NEW:

   syntactic and semantic requirements of YANG 1.1 [RFC7950<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>]. See the exception

   Alternatively,

   These modules SHOULD be written using the YANG 1.1 [RFC7950<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] syntax.

   YANG 1.0 [RFC6020<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc6020&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=L8LZohUWZQHgCc69tSH78w3mmeBF7ZpEaYGfDPYf5-8&e=>] syntax MAY be used if no YANG 1.1 constructs or

The sentence such as:

 - section 3, editorial:

   Internet-Draft or RFC:

   The guidelines in this document refer mainly to a normative complete

   YANG fragments as well.

- section 3.2

   the file name specified in Section 5.2 of [RFC7950]<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950-23section-2D5.2&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=oQY6lhhjRuOEYy_Nf-7HG6_-eMgwX7xZg4VKNHjnTMc&e=>.  The name string

   <CODE BEGINS> file "[email-masked]"<mailto:[email-masked]>

- section 3.2.1

   (Refer to the example in the next section.)
It should be in section 3.4.
Btw, no need to have the specifications for each diagram!
Also, we want to add some guidelines on how to reference the tree diagram convention
For ex: no need to copy over the conventions
Basically, we just need: https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03#section-1.3<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03-23section-2D1.3&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=QlnrbnGZEo-zQYzG9AWk86a_m22IcpBnGQkewEWHaxQ&e=>

   (from https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03#section-1.3<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03-23section-2D1.3&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=QlnrbnGZEo-zQYzG9AWk86a_m22IcpBnGQkewEWHaxQ&e=>),

   Tree Diagrams

   [I-D.ietf-netmod-yang-tree-diagrams<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03-23ref-2DI-2DD.ietf-2Dnetmod-2Dyang-2Dtree-2Ddiagrams&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=JIdabP77Rz-kArFF6DG3MG5X24_APuPzoGifHNEdpmY&e=>].
- section 3.5
You should add a good example to illustrate the second paragraph (Based on some previous feedback, YANG module designer wants to work from examples)
I would suggest to add https://tools.ietf.org/html/draft-ietf-netmod-rfc8022bis-09#section-2.3<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc8022bis-2D09-23section-2D2.3&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=xuiAQ4ZwzGoAwnyFmJc9HzIdN7xsqTzXQ46FBLTqe8M&e=>

- section 3.6, editorial
OLD:

   example module.

NEW:

- section 3.6

   any reserved words from [RFC2119<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc2119&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=n_u6oaVdTWs-y5ne5fi2pdgK-UigUUngP7d8uhsorxM&e=>].

- section 3.10

Mention yanglint.

- section 3.11

You might consider the addition of xym https://github.com/xym-tool/xym<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_xym-2Dtool_xym&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=eULAfGo_CBVjbFXGx49HR73USrKXjCrL-XaAWKdXlKc&e=>

- section 3.12

- section 4.6.x

   'obsolete'.

   'obsolete'.

- section 4.8

   present.

- section 4.10

   created.

What about NMDA?

The example of the abstract in https://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=RpSEervHdcDQlS0Ak-5TVbf3I_oR5bXvhGR68djvPSo&e=> could be mentioned.

In the same section about "top-level data definitions", any guidelines in connection with https://datatracker.ietf.org/doc/draft-ietf-rtgwg-lne-model/<https://urldefense.proofpoint.com/v2/url?u=https-3A__datatracker.ietf.org_doc_draft-2Dietf-2Drtgwg-2Dlne-2Dmodel_&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=uuC62eM2sOBVQxxVTyk2UcxAnOiTqydTayi7j764e8w&e=> and schema mount?

Too early?

In section 4.23, add the [I-D.ietf-netmod-revised-datastores<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc6087bis-2D16-23ref-2DI-2DD.ietf-2Dnetmod-2Drevised-2Ddatastores&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=szYbRXpXn09E4JmhGLL-8-Te-n7tcA5DSlhzSq6qSUc&e=>] reference next to NMDA

In section 4.23.3

OLD:

   example, the "ietf-interfaces" model in [RFC7223<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7223&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=HrAf_Vwxp2ZT1FBY2GcbPFPLLrob4Dtap2N0IpG7WEI&e=>] will be

NEW:

   example, the "ietf-interfaces" model in [RFC7223<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7223&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=HrAf_Vwxp2ZT1FBY2GcbPFPLLrob4Dtap2N0IpG7WEI&e=>] has been

- section 4.14.2

Something wrong with:

- section 4.17

OLD

NEW

   separate features.

back to section 4.5

NEW:

Regards, Benoit

---

From: Benoit Claise <[email-masked]>
Date: Thu, 25 Jan 2018 16:34:10 +0100

Kent,
>
> I see a lot of suggestions to reference other drafts as examples.  I 
> would discourage doing that.  I recommend this draft clearly stating 
> the desire, including its own examples if needed.
>
I recall a remark by Rajiv (in cc) during a NETMOD meeting, along the 
lines of:
I want to create a YANG module but I don't have the time/willingness to 
read every single RFCs before doing so. I want a kind of template, along 
with examples on how to populate it.

We have to understand that a document such as RFC6087bis is not for the 
people who know YANG by heart.
So more examples to illustrate the point is obviously better.
Copying examples inside RFC6087bis we could simply references seems a 
waste of time.
>
> Regarding referencing the tree-diagrams draft, I don't agree that 
> having a "Tree Diagrams" section in the Introduction is better than an 
> inline reference where used:
>
> 2) sections having tree diagrams have to reference the section in the 
> Introduction, and why reference the Intro section when it's just as 
> easy to reference the draft?
>
Again, people want easy guidelines/template.

Regards, Benoit
>
> Kent // contributor
>
> On 1/25/18, 6:20 AM, "netmod on behalf of Benoit Claise" 
> <[email-masked] <mailto:[email-masked]> on behalf of 
> [email-masked] <mailto:[email-masked]>> wrote:
>
> Dear all,
>
>
>     documents containing [RFC7950 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] data models.
> This is not inline with:
>     These modules SHOULD be written using the YANG 1.1 [RFC7950 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] syntax.
>     YANG 1.0 [RFC6020 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc6020&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=L8LZohUWZQHgCc69tSH78w3mmeBF7ZpEaYGfDPYf5-8&e=>] syntax MAY be used if no YANG 1.1 constructs or
>     documents containing YANG 1.1 [RFC7950 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] and YANG 1.0 [RFC6020] data models.
> Similarly in section 4
> OLD:
>     
>     syntactic and semantic requirements of YANG [RFC7950 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>].
> NEW:
>     syntactic and semantic requirements of YANG 1.1 [RFC7950 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>]. See the exception
>     These modules SHOULD be written using the YANG 1.1 [RFC7950 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=t8fshSpe0Dhh5uTE8sRNgSXoLTkY-4-nlePaYc1My0A&e=>] syntax.
>     YANG 1.0 [RFC6020 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc6020&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=L8LZohUWZQHgCc69tSH78w3mmeBF7ZpEaYGfDPYf5-8&e=>] syntax MAY be used if no YANG 1.1 constructs or
>     the file name specified inSection 5.2 of [RFC7950] 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7950-23section-2D5.2&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=oQY6lhhjRuOEYy_Nf-7HG6_-eMgwX7xZg4VKNHjnTMc&e=>.  The name string
>     <CODE BEGINS> file"[email-masked]" <mailto:[email-masked]>
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03-23section-2D1.3&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=QlnrbnGZEo-zQYzG9AWk86a_m22IcpBnGQkewEWHaxQ&e=>
>
>         (fromhttps://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03#section-1.3
>     <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03-23section-2D1.3&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=QlnrbnGZEo-zQYzG9AWk86a_m22IcpBnGQkewEWHaxQ&e=>),
>
>     <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03-23ref-2DI-2DD.ietf-2Dnetmod-2Dyang-2Dtree-2Ddiagrams&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=JIdabP77Rz-kArFF6DG3MG5X24_APuPzoGifHNEdpmY&e=>].
>
> - section 3.5
> You should add a good example to illustrate the second paragraph 
> (Based on some previous feedback, YANG module designer wants to work 
> from examples)
> I would suggest to add 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc8022bis-2D09-23section-2D2.3&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=xuiAQ4ZwzGoAwnyFmJc9HzIdN7xsqTzXQ46FBLTqe8M&e=>
>
>
> - section 3.6, editorial
> OLD:
>
>     any reserved words from [RFC2119 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc2119&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=n_u6oaVdTWs-y5ne5fi2pdgK-UigUUngP7d8uhsorxM&e=>].
> You might consider the addition of xymhttps://github.com/xym-tool/xym 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_xym-2Dtool_xym&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=eULAfGo_CBVjbFXGx49HR73USrKXjCrL-XaAWKdXlKc&e=>
> - section 3.12
> The example of the abstract inhttps://tools.ietf.org/html/draft-ietf-netmod-rfc7223bis-03 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc7223bis-2D03&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=RpSEervHdcDQlS0Ak-5TVbf3I_oR5bXvhGR68djvPSo&e=>  could be mentioned.
> In the same section about "top-level data definitions", any guidelines in connection withhttps://datatracker.ietf.org/doc/draft-ietf-rtgwg-lne-model/ 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__datatracker.ietf.org_doc_draft-2Dietf-2Drtgwg-2Dlne-2Dmodel_&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=uuC62eM2sOBVQxxVTyk2UcxAnOiTqydTayi7j764e8w&e=>  and schema mount?
> Too early?
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc6087bis-2D16-23ref-2DI-2DD.ietf-2Dnetmod-2Drevised-2Ddatastores&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=szYbRXpXn09E4JmhGLL-8-Te-n7tcA5DSlhzSq6qSUc&e=>] reference next to NMDA
> In section 4.23.3
> OLD:
>     example, the "ietf-interfaces" model in [RFC7223 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7223&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=HrAf_Vwxp2ZT1FBY2GcbPFPLLrob4Dtap2N0IpG7WEI&e=>] will be
>     example, the "ietf-interfaces" model in [RFC7223 
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc7223&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=LtO2RQQIegWlN4MIzNkbubIXiwPDj_Uk_qYxqyLA_mc&s=HrAf_Vwxp2ZT1FBY2GcbPFPLLrob4Dtap2N0IpG7WEI&e=>] has been