Tech-invite3GPPspecsGlossariesIETFRFCsGroupsSIPABNFsWorld Map

RFC 8407

BCP 216
Pages: 63
Top     in Index     Prev     Next
in Group Index     Prev in Group     No Next: Highest Number in Group     Group: NETMOD

Guidelines for Authors and Reviewers of Documents Containing YANG Data Models

Part 1 of 4, p. 1 to 15
None       Next Section

Obsoletes:    6087


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                        A. Bierman
Request for Comments: 8407                                     YumaWorks
BCP: 216                                                    October 2018
Obsoletes: 6087
Category: Best Current Practice
ISSN: 2070-1721


           Guidelines for Authors and Reviewers of Documents
                      Containing YANG Data Models

Abstract

   This memo provides guidelines for authors and reviewers of
   specifications containing YANG modules.  Recommendations and
   procedures are defined, which are intended to increase
   interoperability and usability of Network Configuration Protocol
   (NETCONF) and RESTCONF protocol implementations that utilize YANG
   modules.  This document obsoletes RFC 6087.

Status of This Memo

   This memo documents an Internet Best Current Practice.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   BCPs is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc8407.

Copyright Notice

   Copyright (c) 2018 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Top       Page 2 
Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Changes since RFC 6087  . . . . . . . . . . . . . . . . .   5
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   6
     2.1.  NETCONF Terms . . . . . . . . . . . . . . . . . . . . . .   7
     2.2.  YANG Terms  . . . . . . . . . . . . . . . . . . . . . . .   7
     2.3.  NMDA Terms  . . . . . . . . . . . . . . . . . . . . . . .   7
     2.4.  Requirements Notation . . . . . . . . . . . . . . . . . .   8
   3.  General Documentation Guidelines  . . . . . . . . . . . . . .   8
     3.1.  Module Copyright  . . . . . . . . . . . . . . . . . . . .   9
     3.2.  Code Components . . . . . . . . . . . . . . . . . . . . .   9
       3.2.1.  Example Modules . . . . . . . . . . . . . . . . . . .   9
     3.3.  Terminology Section . . . . . . . . . . . . . . . . . . .  10
     3.4.  Tree Diagrams . . . . . . . . . . . . . . . . . . . . . .  10
     3.5.  Narrative Sections  . . . . . . . . . . . . . . . . . . .  10
     3.6.  Definitions Section . . . . . . . . . . . . . . . . . . .  11
     3.7.  Security Considerations Section . . . . . . . . . . . . .  11
       3.7.1.  Security Considerations Section Template  . . . . . .  12
     3.8.  IANA Considerations Section . . . . . . . . . . . . . . .  13
       3.8.1.  Documents That Create a New Namespace . . . . . . . .  14
       3.8.2.  Documents That Extend an Existing Namespace . . . . .  14
     3.9.  References Sections . . . . . . . . . . . . . . . . . . .  14
     3.10. Validation Tools  . . . . . . . . . . . . . . . . . . . .  14
     3.11. Module Extraction Tools . . . . . . . . . . . . . . . . .  15
     3.12. Module Usage Examples . . . . . . . . . . . . . . . . . .  15
   4.  YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . .  15
     4.1.  Module Naming Conventions . . . . . . . . . . . . . . . .  16
     4.2.  Prefixes  . . . . . . . . . . . . . . . . . . . . . . . .  17
     4.3.  Identifiers . . . . . . . . . . . . . . . . . . . . . . .  18
       4.3.1.  Identifier Naming Conventions . . . . . . . . . . . .  18
     4.4.  Defaults  . . . . . . . . . . . . . . . . . . . . . . . .  19
     4.5.  Conditional Statements  . . . . . . . . . . . . . . . . .  19
     4.6.  XPath Usage . . . . . . . . . . . . . . . . . . . . . . .  20
       4.6.1.  XPath Evaluation Contexts . . . . . . . . . . . . . .  20
       4.6.2.  Function Library  . . . . . . . . . . . . . . . . . .  21
       4.6.3.  Axes  . . . . . . . . . . . . . . . . . . . . . . . .  22
       4.6.4.  Types . . . . . . . . . . . . . . . . . . . . . . . .  23
       4.6.5.  Wildcards . . . . . . . . . . . . . . . . . . . . . .  24
       4.6.6.  Boolean Expressions . . . . . . . . . . . . . . . . .  24
     4.7.  YANG Definition Lifecycle Management  . . . . . . . . . .  25
     4.8.  Module Header, Meta, and Revision Statements  . . . . . .  26
     4.9.  Namespace Assignments . . . . . . . . . . . . . . . . . .  28
     4.10. Top-Level Data Definitions  . . . . . . . . . . . . . . .  29
     4.11. Data Types  . . . . . . . . . . . . . . . . . . . . . . .  30
       4.11.1.  Fixed-Value Extensibility  . . . . . . . . . . . . .  30
       4.11.2.  Patterns and Ranges  . . . . . . . . . . . . . . . .  31
       4.11.3.  Enumerations and Bits  . . . . . . . . . . . . . . .  32

Top      ToC       Page 3 
       4.11.4.  Union Types  . . . . . . . . . . . . . . . . . . . .  33
       4.11.5.  Empty and Boolean  . . . . . . . . . . . . . . . . .  34
     4.12. Reusable Type Definitions . . . . . . . . . . . . . . . .  35
     4.13. Reusable Groupings  . . . . . . . . . . . . . . . . . . .  35
     4.14. Data Definitions  . . . . . . . . . . . . . . . . . . . .  36
       4.14.1.  Non-Presence Containers  . . . . . . . . . . . . . .  38
       4.14.2.  Top-Level Data Nodes . . . . . . . . . . . . . . . .  38
     4.15. Operation Definitions . . . . . . . . . . . . . . . . . .  39
     4.16. Notification Definitions  . . . . . . . . . . . . . . . .  39
     4.17. Feature Definitions . . . . . . . . . . . . . . . . . . .  40
     4.18. YANG Data Node Constraints  . . . . . . . . . . . . . . .  41
       4.18.1.  Controlling Quantity . . . . . . . . . . . . . . . .  41
       4.18.2.  "must" versus "when" . . . . . . . . . . . . . . . .  41
     4.19. "augment" Statements  . . . . . . . . . . . . . . . . . .  41
       4.19.1.  Conditional Augment Statements . . . . . . . . . . .  41
       4.19.2.  Conditionally Mandatory Data Definition Statements .  42
     4.20. Deviation Statements  . . . . . . . . . . . . . . . . . .  43
     4.21. Extension Statements  . . . . . . . . . . . . . . . . . .  44
     4.22. Data Correlation  . . . . . . . . . . . . . . . . . . . .  45
       4.22.1.  Use of "leafref" for Key Correlation . . . . . . . .  46
     4.23. Operational State . . . . . . . . . . . . . . . . . . . .  47
       4.23.1.  Combining Operational State and Configuration Data .  47
       4.23.2.  Representing Operational Values of Configuration
                Data . . . . . . . . . . . . . . . . . . . . . . . .  47
       4.23.3.  NMDA Transition Guidelines . . . . . . . . . . . . .  48
     4.24. Performance Considerations  . . . . . . . . . . . . . . .  52
     4.25. Open Systems Considerations . . . . . . . . . . . . . . .  52
     4.26. Guidelines for Constructs Specific to YANG 1.1  . . . . .  53
       4.26.1.  Importing Multiple Revisions . . . . . . . . . . . .  53
       4.26.2.  Using Feature Logic  . . . . . . . . . . . . . . . .  53
       4.26.3.  "anyxml" versus "anydata"  . . . . . . . . . . . . .  53
       4.26.4.  "action" versus "rpc"  . . . . . . . . . . . . . . .  53
     4.27. Updating YANG Modules (Published versus Unpublished)  . .  54
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  55
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  55
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  56
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  56
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  57
   Appendix A.  Module Review Checklist  . . . . . . . . . . . . . .  59
   Appendix B.  YANG Module Template . . . . . . . . . . . . . . . .  61
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  62
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  63

Top      ToC       Page 4 
1.  Introduction

   The standardization of network configuration interfaces for use with
   network configuration management protocols, such as the Network
   Configuration Protocol [RFC6241] and the RESTCONF protocol [RFC8040],
   requires a modular set of data models that can be reused and extended
   over time.

   This document defines a set of usage guidelines for documents
   containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models.
   YANG is used to define the data structures, protocol operations, and
   notification content used within a NETCONF and/or RESTCONF server.  A
   NETCONF or RESTCONF server that supports a particular YANG module
   will support client NETCONF and/or RESTCONF operation requests, as
   indicated by the specific content defined in the YANG module.

   Many YANG constructs are defined as optional to use, such as the
   "description" statement.  However, in order to make YANG modules more
   useful, it is desirable to define a set of usage guidelines that
   entails a higher level of compliance than the minimum level defined
   in the YANG specification [RFC7950].

   In addition, YANG allows constructs such as infinite length
   identifiers and string values, or top-level mandatory nodes, that a
   compliant server is not required to support.  Only constructs that
   all servers are required to support can be used in IETF YANG modules.

   This document defines usage guidelines related to the NETCONF
   operations layer and NETCONF content layer, as defined in [RFC6241],
   and the RESTCONF methods and RESTCONF resources, as defined in
   [RFC8040].

   These guidelines are intended to be used by authors and reviewers to
   improve the readability and interoperability of published YANG data
   models.

   Note that this document is not a YANG tutorial, and the reader is
   expected to know the YANG data modeling language before implementing
   the guidance in this document.

Top      ToC       Page 5 
1.1.  Changes since RFC 6087

   The following changes have been made to the guidelines published in
   [RFC6087]:

   o  Updated NETCONF reference from RFC 4741 to RFC 6241

   o  Updated NETCONF over the Secure Shell (SSH) citation from RFC 4742
      to RFC 6242

   o  Updated YANG Types reference from RFC 6021 to RFC 6991

   o  Updated obsolete URLs for IETF resources

   o  Changed top-level data node guideline

   o  Clarified XML Path Language (XPath) usage for a literal value
      representing a YANG identity

   o  Clarified XPath usage for a when-stmt

   o  Clarified XPath usage for "preceding-sibling" and
      "following-sibling" axes

   o  Added terminology guidelines

   o  Added mention of RFC 8174, which updates RFC 2119 by clarifying
      the use of capitalized key words

   o  Added YANG tree diagram guidelines

   o  Updated XPath guidelines for type conversions and function library
      usage

   o  Updated "Data Types" section

   o  Updated "Notification Definitions" section

   o  Clarified conditional key leaf nodes

   o  Clarified usage of "uint64" and "int64" data types

   o  Added text on YANG feature usage

   o  Added "Identifier Naming Conventions" section

   o  Clarified use of mandatory nodes with conditional augmentations

Top      ToC       Page 6 
   o  Clarified namespace and domain conventions for example modules

   o  Clarified conventions for identifying code components

   o  Added YANG 1.1 guidelines

   o  Added "YANG Data Node Constraints" section

   o  Added mention of the RESTCONF protocol

   o  Added guidelines for datastores revised by the Network Management
      Datastore Architecture (NMDA)

2.  Terminology

   The following terms are used throughout this document:

   o  published: A stable release of a module or submodule.  For
      example, the "Request for Comments" described in Section 2.1 of
      [RFC2026] is considered a stable publication.

   o  unpublished: An unstable release of a module or submodule.  For
      example the "Internet-Draft" described in Section 2.2 of [RFC2026]
      is considered an unstable publication that is a work in progress,
      subject to change at any time.

   o  YANG fragment: A set of YANG statements that are not intended to
      represent a complete YANG module or submodule.  These statements
      are not intended for actual use, except to provide an example of
      YANG statement usage.  The invalid syntax "..." is sometimes used
      to indicate that additional YANG statements would be present in a
      real YANG module.

   o  YANG tree diagram: A diagram representing the contents of a YANG
      module, as defined in [RFC8340].  It is also called a "tree
      diagram".

Top      ToC       Page 7 
2.1.  NETCONF Terms

   The following terms are defined in [RFC6241] and are not redefined
   here:

   o  capabilities

   o  client

   o  operation

   o  server

2.2.  YANG Terms

   The following terms are defined in [RFC7950] and are not redefined
   here:

   o  data node

   o  module

   o  namespace

   o  submodule

   o  version

   o  YANG

   o  YIN

   Note that the term 'module' may be used as a generic term for a YANG
   module or submodule.  When describing properties that are specific to
   submodules, the term 'submodule' is used instead.

2.3.  NMDA Terms

   The following terms are defined in [RFC8342] and are not redefined
   here:

   o  configuration

   o  conventional configuration datastore

   o  datastore

Top      ToC       Page 8 
   o  operational state

   o  operational state datastore

2.4.  Requirements Notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  General Documentation Guidelines

   YANG modules under review are likely to be contained in Internet-
   Drafts (I-Ds).  All guidelines for I-D authors [ID-Guidelines] MUST
   be followed.  The guidelines for RFCs should be followed and are
   defined in the following: [RFC7322] (and any future RFCs that
   obsolete it), [RFC-STYLE], and [RFC7841].

   The following sections MUST be present in an I-D containing a module:

   o  Narrative sections

   o  Definition sections

   o  Security Considerations section

   o  IANA Considerations section

   o  References section

   There are three usage scenarios for YANG that can appear in an I-D 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 module or
   submodule but may be applicable to example modules and YANG fragments
   as well.

Top      ToC       Page 9 
3.1.  Module Copyright

   The module "description" statement MUST contain a reference to the
   latest approved IETF Trust Copyright statement, which is available
   online at:

       <https://trustee.ietf.org/license-info/>

3.2.  Code Components

   Each normative YANG module or submodule contained within an I-D or
   RFC is considered to be a code component.  The strings "<CODE
   BEGINS>" and "<CODE ENDS>" MUST be used to identify each code
   component.

   The "<CODE BEGINS>" tag SHOULD be followed by a string identifying
   the file name specified in Section 5.2 of [RFC7950].  The name string
   form that includes the revision date SHOULD be used.  The revision
   date MUST match the date used in the most recent revision of the
   module.

   The following example is for the "2016-03-20" revision of the
   "ietf-foo" module:

   <CODE BEGINS> file "ietf-foo@2016-03-20.yang"

       module ietf-foo {
         namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
         prefix "foo";
         organization "...";
         contact "...";
         description "...";
         revision 2016-03-20 {
           description "Latest revision";
           reference "RFC XXXX: Foo Protocol";
         }
         // ... more statements
       }

   <CODE ENDS>

3.2.1.  Example Modules

   Example modules are not code components.  The <CODE BEGINS>
   convention MUST NOT be used for example modules.

   An example module SHOULD be named using the term "example", followed
   by a hyphen, followed by a descriptive name, e.g., "example-toaster".

Top      ToC       Page 10 
   See Section 4.9 regarding the namespace guidelines for example
   modules.

3.3.  Terminology Section

   A terminology section MUST be present if any terms are defined in the
   document or if any terms are imported from other documents.

3.4.  Tree Diagrams

   YANG tree diagrams provide a concise representation of a YANG module
   and SHOULD be included to help readers understand YANG module
   structure.  Guidelines on tree diagrams can be found in Section 3 of
   [RFC8340].

   If YANG tree diagrams are used, then an informative reference to the
   YANG tree diagrams specification MUST be included in the document.
   Refer to Section 2.2 of [RFC8349] for an example of such a reference.

3.5.  Narrative Sections

   The narrative part MUST include an overview section that describes
   the scope and field of application of the module(s) defined by the
   specification and that specifies the relationship (if any) of these
   modules to other standards, particularly to standards containing
   other YANG modules.  The narrative part SHOULD include one or more
   sections to briefly describe the structure of the modules defined in
   the specification.

   If the module or modules defined by the specification imports
   definitions from other modules (except for those defined in [RFC7950]
   or [RFC6991]) or are always implemented in conjunction with other
   modules, then those facts MUST be noted in the overview section; any
   special interpretations of definitions in other modules MUST be noted
   as well.  Refer to Section 2.3 of [RFC8349] for an example of this
   overview section.

   If the document contains a YANG module(s) that is compliant with NMDA
   [RFC8342], then the Introduction section should mention this fact.

   Example:

     The YANG data model in this document conforms to the Network
     Management Datastore Architecture defined in
     RFC 8342.

Top      ToC       Page 11 
   Consistent indentation SHOULD be used for all examples, including
   YANG fragments and protocol message instance data.  If line wrapping
   is done for formatting purposes, then this SHOULD be noted, as shown
   in the following example:

      [note: '\' line wrapping for formatting only]

      <myleaf xmlns="tag:example.com,2017:example-two">\
        this is a long value so the line needs to wrap to stay\
        within 72 characters\
      </myleaf>

3.6.  Definitions Section

   This section contains the module(s) defined by the specification.
   These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax.
   YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or
   semantics are needed in the module.  If any of the imported YANG
   modules are written using YANG 1.1, then the module MUST be written
   using YANG 1.1.

   A YIN syntax version of the module MAY also be present in the
   document.  There MAY also be other types of modules present in the
   document, such as Structure of Management Information Version 2
   (SMIv2), which are not affected by these guidelines.

   Note that if the module itself is considered normative and not an
   example module or example YANG fragment, then all YANG statements
   within a YANG module are considered normative.  The use of keywords
   defined in [RFC2119] and [RFC8174] apply to YANG "description"
   statements in normative modules exactly as they would in any other
   normative section.

   Example YANG modules and example YANG fragments MUST NOT contain any
   normative text, including any all-uppercase reserved words from
   [RFC2119] and [RFC8174].

   Consistent indentation and formatting SHOULD be used in all YANG
   statements within a module.

   See Section 4 for guidelines on YANG usage.

3.7.  Security Considerations Section

   Each specification that defines one or more modules MUST contain a
   section that discusses security considerations relevant to those
   modules.

Top      ToC       Page 12 
   This section MUST be patterned after the latest approved template
   (available at <https://trac.ietf.org/trac/ops/wiki/yang-security-
   guidelines>).  Section 3.7.1 contains the security considerations
   template dated 2013-05-08 and last updated on 2018-07-02.  Authors
   MUST check the web page at the URL listed above in case there is a
   more recent version available.

   In particular:

   o  Writable data nodes that could be especially disruptive if abused
      MUST be explicitly listed by name, and the associated security
      risks MUST be explained.

   o  Readable data nodes that contain especially sensitive information
      or that raise significant privacy concerns MUST be explicitly
      listed by name, and the reasons for the sensitivity/privacy
      concerns MUST be explained.

   o  Operations (i.e., YANG "rpc" statements) that are potentially
      harmful to system behavior or that raise significant privacy
      concerns MUST be explicitly listed by name, and the reasons for
      the sensitivity/privacy concerns MUST be explained.

3.7.1.  Security Considerations Section Template

   X.  Security Considerations

   The YANG module specified in this document defines a schema for data
   that is designed to be accessed via network management protocols such
   as NETCONF [RFC6241] or RESTCONF [RFC8040].  The lowest NETCONF layer
   is the secure transport layer, and the mandatory-to-implement secure
   transport is Secure Shell (SSH) [RFC6242].  The lowest RESTCONF layer
   is HTTPS, and the mandatory-to-implement secure transport is TLS
   [RFC8446].

   The NETCONF access control model [RFC8341] provides the means to
   restrict access for particular NETCONF or RESTCONF users to a
   preconfigured subset of all available NETCONF or RESTCONF protocol
   operations and content.

    -- if you have any writable data nodes (those are all the
    -- "config true" nodes, and remember, that is the default)
    -- describe their specific sensitivity or vulnerability.

   There are a number of data nodes defined in this YANG module that are
   writable/creatable/deletable (i.e., "config true", which is the
   default).  These data nodes may be considered sensitive or vulnerable
   in some network environments.  Write operations (e.g., edit-config)

Top      ToC       Page 13 
   to these data nodes without proper protection can have a negative
   effect on network operations.  These are the subtrees and data nodes
   and their sensitivity/vulnerability:

   <list subtrees and data nodes and state why they are sensitive>

    -- for all YANG modules you must evaluate whether any readable data
    -- nodes (those are all the "config false" nodes, but also all other
    -- nodes, because they can also be read via operations like get or
    -- get-config) are sensitive or vulnerable (for instance, if they
    -- might reveal customer information or violate personal privacy
    -- laws such as those of the European Union if exposed to
    -- unauthorized parties)

   Some of the readable data nodes in this YANG module may be considered
   sensitive or vulnerable in some network environments.  It is thus
   important to control read access (e.g., via get, get-config, or
   notification) to these data nodes.  These are the subtrees and data
   nodes and their sensitivity/vulnerability:

   <list subtrees and data nodes and state why they are sensitive>

    -- if your YANG module has defined any RPC operations
    -- describe their specific sensitivity or vulnerability.

   Some of the RPC operations in this YANG module may be considered
   sensitive or vulnerable in some network environments.  It is thus
   important to control access to these operations.  These are the
   operations and their sensitivity/vulnerability:

   <list RPC operations and state why they are sensitive>

3.8.  IANA Considerations Section

   In order to comply with IESG policy as set forth in
   <https://www.ietf.org/id-info/checklist.html>, every I-D that is
   submitted to the IESG for publication MUST contain an IANA
   Considerations section.  The requirements for this section vary
   depending on what actions are required of the IANA.  If there are no
   IANA considerations applicable to the document, then the IANA
   Considerations section will state that "This document has no IANA
   actions".  Refer to the guidelines in [RFC8126] for more details.

   Each normative YANG module MUST be registered in both the "IETF XML
   Registry" [RFC3688] [IANA-XML] and the "YANG Module Names" registry
   [RFC6020] [IANA-MOD-NAMES].  This applies to new modules and updated
   modules.  An example of an update registration for the
   "ietf-template" module can be found in Section 5.

Top      ToC       Page 14 
3.8.1.  Documents That Create a New Namespace

   If an I-D defines a new namespace that is to be administered by the
   IANA, then the document MUST include an IANA Considerations section
   that specifies how the namespace is to be administered.

   Specifically, if any YANG module namespace statement value contained
   in the document is not already registered with IANA, then a new entry
   in the "ns" subregistry within the "IETF XML Registry" MUST be
   requested from the IANA.

3.8.2.  Documents That Extend an Existing Namespace

   It is possible to extend an existing namespace using a YANG submodule
   that belongs to an existing module already administered by IANA.  In
   this case, the document containing the main module MUST be updated to
   use the latest revision of the submodule.

3.9.  References Sections

   For every import or include statement that appears in a module
   contained in the specification that identifies a module in a separate
   document, a corresponding normative reference to that document MUST
   appear in the Normative References section.  The reference MUST
   correspond to the specific module version actually used within the
   specification.

   For every normative reference statement that appears in a module
   contained in the specification that identifies a separate document, a
   corresponding normative reference to that document SHOULD appear in
   the Normative References section.  The reference SHOULD correspond to
   the specific document version actually used within the specification.
   If the reference statement identifies an informative reference that
   identifies a separate document, a corresponding informative reference
   to that document MAY appear in the Informative References section.

3.10.  Validation Tools

   All modules need to be validated before submission in an I-D.  The
   'pyang' YANG compiler is freely available from GitHub:

     <https://github.com/mbj4668/pyang>

   If the 'pyang' compiler is used to validate a normative module, then
   the "--ietf" command-line option MUST be used to identify any IETF
   guideline issues.

Top      ToC       Page 15 
   If the 'pyang' compiler is used to validate an example module, then
   the "--ietf" command-line option MAY be used to identify any IETF
   guideline issues.

   The "yanglint" program is also freely available from GitHub.

      <https://github.com/CESNET/libyang>

   This tool can be used to validate XPath statements within YANG
   modules.

3.11.  Module Extraction Tools

   A version of 'rfcstrip' that will extract YANG modules from an I-D or
   RFC is available.  The 'rfcstrip' tool that supports YANG module
   extraction is freely available at:

     <https://github.com/mbj4668/rfcstrip>

   This tool can be used to verify that the "<CODE BEGINS>" and "<CODE
   ENDS>" tags are used correctly and that the normative YANG modules
   can be extracted correctly.

   The "xym" tool is freely available on GitHub and can be used to
   extract YANG modules from a document.

      <https://github.com/xym-tool/xym>

3.12.  Module Usage Examples

   Each specification that defines one or more modules SHOULD contain
   usage examples, either throughout the document or in an appendix.
   This includes example instance document snippets in an appropriate
   encoding (e.g., XML and/or JSON) to demonstrate the intended usage of
   the YANG module(s).  Example modules MUST be validated.  Refer to
   Section 3.10 for tools that validate YANG modules.  If IP addresses
   are used, then a mix of either IPv4 and IPv6 addresses or IPv6
   addresses exclusively SHOULD be used in the examples.



(page 15 continued on part 2)

Next Section