RFC 8407
Guidelines for Authors and Reviewers of Documents Containing YANG Data Models
Pages: 63
Best Current Practice: 216
→ Errata
Obsoletes: 6087
Updated by: 8819
Best Current Practice: 216
→ Errata
Obsoletes: 6087
Updated by: 8819
Part 1 of 4 – Pages 1 to 15
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 ModelsAbstract
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.
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
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
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.
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
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".
2.1. NETCONF Terms
The following terms are defined in [RFC6241] and are not redefined here: o capabilities o client o operation o server2.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
o operational state o operational state datastore2.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.
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".
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.
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.
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)
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.
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.
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)