From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc8407.txt | 3531 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3531 insertions(+) create mode 100644 doc/rfc/rfc8407.txt (limited to 'doc/rfc/rfc8407.txt') diff --git a/doc/rfc/rfc8407.txt b/doc/rfc/rfc8407.txt new file mode 100644 index 0000000..cee4afd --- /dev/null +++ b/doc/rfc/rfc8407.txt @@ -0,0 +1,3531 @@ + + + + + + +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. + + + +Bierman Best Current Practice [Page 1] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +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 + + + +Bierman Best Current Practice [Page 2] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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 + + + + + + + + + +Bierman Best Current Practice [Page 3] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +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. + + + + + + + + + + + + +Bierman Best Current Practice [Page 4] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +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 + + + + +Bierman Best Current Practice [Page 5] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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". + + + + + + + + + + + + + + + +Bierman Best Current Practice [Page 6] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +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 + + + + + +Bierman Best Current Practice [Page 7] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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. + + + + + + + +Bierman Best Current Practice [Page 8] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +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: + + + +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 "" and "" MUST be used to identify each code + component. + + The "" 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: + + 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 + } + + + +3.2.1. Example Modules + + Example modules are not code components. The + 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". + + + +Bierman Best Current Practice [Page 9] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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. + + + + + + +Bierman Best Current Practice [Page 10] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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] + + \ + this is a long value so the line needs to wrap to stay\ + within 72 characters\ + + +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. + + + + +Bierman Best Current Practice [Page 11] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + This section MUST be patterned after the latest approved template + (available at ). 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) + + + +Bierman Best Current Practice [Page 12] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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: + + + + -- 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: + + + + -- 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: + + + +3.8. IANA Considerations Section + + In order to comply with IESG policy as set forth in + , 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. + + + +Bierman Best Current Practice [Page 13] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +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: + + + + 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. + + + + + +Bierman Best Current Practice [Page 14] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + 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. + + + + 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: + + + + This tool can be used to verify that the "" and "" 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. + + + +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. + +4. YANG Usage Guidelines + + Modules in IETF Standards Track specifications MUST comply with all + syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the + exception for YANG 1.0 in Section 3.6. The guidelines in this + section are intended to supplement the YANG specification [RFC7950], + which is intended to define a minimum set of conformance + requirements. + + + + +Bierman Best Current Practice [Page 15] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + In order to promote interoperability and establish a set of practices + based on previous experience, the following sections establish usage + guidelines for specific YANG constructs. + + Only guidelines that clarify or restrict the minimum conformance + requirements are included here. + +4.1. Module Naming Conventions + + Normative modules contained in Standards Track documents MUST be + named according to the guidelines in the IANA Considerations section + of [RFC7950]. + + A distinctive word or abbreviation (e.g., protocol name or working + group abbreviation) SHOULD be used in the module name. If new + definitions are being defined to extend one or more existing modules, + then the same word or abbreviation should be reused, instead of + creating a new one. + + All published module names MUST be unique. For a YANG module + published in an RFC, this uniqueness is guaranteed by IANA. For + unpublished modules, the authors need to check that no other work in + progress is using the same module name. + + Example modules are non-normative and SHOULD be named with the prefix + "example-". + + It is suggested that a stable prefix be selected that represents the + entire organization. All normative YANG modules published by the + IETF MUST begin with the prefix "ietf-". Another standards + organization, such as the IEEE, might use the prefix "ieee-" for all + YANG modules. + + Once a module name is published, it MUST NOT be reused, even if the + RFC containing the module is reclassified to "Historic" status. A + module name cannot be changed in YANG, and this would be treated as a + new module, not a name change. + + + + + + + + + + + + + + +Bierman Best Current Practice [Page 16] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.2. Prefixes + + All YANG definitions are scoped by the module containing the + definition being referenced. This allows definitions from multiple + modules to be used, even if the names are not unique. In the example + below, the identifier "foo" is used in all three modules: + + module example-foo { + namespace "tag:example.com,2017:example-foo"; + prefix f; + + container foo; + } + + module example-bar { + namespace "tag:example.com,2017:example-bar"; + prefix b; + + typedef foo { type uint32; } + } + + module example-one { + namespace "tag:example.com,2017:example-one"; + prefix one; + import example-foo { prefix f; } + import example-bar { prefix b; } + + augment "/f:foo" { + leaf foo { type b:foo; } + } + } + + YANG defines the following rules for prefix usage: + + o Prefixes are never used for built-in data types and YANG keywords. + + o A prefix MUST be used for any external statement (i.e., a + statement defined with the YANG "extension" statement). + + o The proper module prefix MUST be used for all identifiers imported + from other modules. + + o The proper module prefix MUST be used for all identifiers included + from a submodule. + + + + + + + +Bierman Best Current Practice [Page 17] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The following guidelines apply to prefix usage of the current (local) + module: + + o The local module prefix SHOULD be used instead of no prefix in all + path expressions. + + o The local module prefix MUST be used instead of no prefix in all + "default" statements for an "identityref" or "instance-identifier" + data type. + + o The local module prefix MAY be used for references to typedefs, + groupings, extensions, features, and identities defined in the + module. + + Prefix values SHOULD be short but are also likely to be unique. + Prefix values SHOULD NOT conflict with known modules that have been + previously published. + +4.3. Identifiers + + Identifiers for all YANG identifiers in published modules MUST be + between 1 and 64 characters in length. These include any construct + specified as an "identifier-arg-str" token in the ABNF in Section 14 + of [RFC7950]. + +4.3.1. Identifier Naming Conventions + + Identifiers SHOULD follow a consistent naming pattern throughout the + module. Only lowercase letters, numbers, and dashes SHOULD be used + in identifier names. Uppercase characters, the period character, and + the underscore character MAY be used if the identifier represents a + well-known value that uses these characters. YANG does not permit + any other characters in YANG identifiers. + + Identifiers SHOULD include complete words and/or well-known acronyms + or abbreviations. Child nodes within a container or list SHOULD NOT + replicate the parent identifier. YANG identifiers are hierarchical + and are only meant to be unique within the set of sibling nodes + defined in the same module namespace. + + It is permissible to use common identifiers such as "name" or "id" in + data definition statements, especially if these data nodes share a + common data type. + + Identifiers SHOULD NOT carry any special semantics that identify data + modeling properties. Only YANG statements and YANG extension + statements are designed to convey machine-readable data modeling + properties. For example, naming an object "config" or "state" does + + + +Bierman Best Current Practice [Page 18] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + not change whether it is configuration data or state data. Only + defined YANG statements or YANG extension statements can be used to + assign semantics in a machine-readable format in YANG. + +4.4. Defaults + + In general, it is suggested that substatements containing very common + default values SHOULD NOT be present. The following substatements + are commonly used with the default value, which would make the module + difficult to read if used everywhere they are allowed. + + +--------------+---------------+ + | Statement | Default Value | + +--------------+---------------+ + | config | true | + | mandatory | false | + | max-elements | unbounded | + | min-elements | 0 | + | ordered-by | system | + | status | current | + | yin-element | false | + +--------------+---------------+ + + Statement Defaults + +4.5. Conditional Statements + + A module may be conceptually partitioned in several ways, using the + "if-feature" and/or "when" statements. + + Data model designers need to carefully consider all modularity + aspects, including the use of YANG conditional statements. + + 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. The defined "feature" statement SHOULD + then be used in the conditional "if-feature" statement referencing + the optional data definition. + + If any notification data, or any data definition, for a non- + configuration data node is not mandatory, then the server may or may + not be required to return an instance of this data node. If any + conditional requirements exist for returning the data node in a + notification payload or retrieval request, they MUST be documented + somewhere. For example, a "when" or "if-feature" statement could + apply to the data node, or the conditional requirements could be + explained in a "description" statement within the data node or one of + its ancestors (if any). + + + +Bierman Best Current Practice [Page 19] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + If any "if-feature" statements apply to a list node, then the same + "if-feature" statements MUST apply to any key leaf nodes for the + list. There MUST NOT be any "if-feature" statements applied to any + key leafs that do not also apply to the parent list node. + + There SHOULD NOT be any "when" statements applied to a key leaf node. + It is possible that a "when" statement for an ancestor node of a key + leaf will have the exact node-set result as the key leaf. In such a + case, the "when" statement for the key leaf is redundant and SHOULD + be avoided. + +4.6. XPath Usage + + This section describes guidelines for using the XML Path Language + (XPath) [W3C.REC-xpath] within YANG modules. + +4.6.1. XPath Evaluation Contexts + + YANG defines five separate contexts for evaluation of XPath + statements: + + 1. The "running" datastore: collection of all YANG configuration + data nodes. The document root is the conceptual container (e.g., + "config" in the "edit-config" operation), which is the parent of + all top-level data definition statements with a "config" + statement value of "true". + + 2. State data + the "running" datastore: collection of all YANG data + nodes. The document root is the conceptual container, parent of + all top-level data definition statements. + + 3. Notification: an event notification document. The document root + is the notification element. + + 4. RPC Input: The document root is the conceptual "input" node, + which is the parent of all RPC input parameter definitions. + + 5. RPC Output: The document root is the conceptual "output" node, + which is the parent of all RPC output parameter definitions. + + + + + + + + + + + + +Bierman Best Current Practice [Page 20] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + Note that these XPath contexts cannot be mixed. For example, a + "when" statement in a notification context cannot reference + configuration data. + + notification foo { + leaf mtu { + // NOT okay because when-stmt context is this notification + when "/if:interfaces/if:interface[name='eth0']"; + type leafref { + // Okay because path-stmt has a different context + path "/if:interfaces/if:interface/if:mtu"; + } + } + } + + It is especially important to consider the XPath evaluation context + for XPath expressions defined in groupings. An XPath expression + defined in a grouping may not be portable, meaning it cannot be used + in multiple contexts and produce proper results. + + If the XPath expressions defined in a grouping are intended for a + particular context, then this context SHOULD be identified in the + "description" statement for the grouping. + +4.6.2. Function Library + + The "position" and "last" functions SHOULD NOT be used. This applies + to implicit use of the "position" function as well (e.g., + '//chapter[42]'). A server is only required to maintain the relative + XML document order of all instances of a particular user-ordered list + or leaf-list. The "position" and "last" functions MAY be used if + they are evaluated in a context where the context node is a user- + ordered "list" or "leaf-list". + + The "id" function SHOULD NOT be used. The "ID" attribute is not + present in YANG documents, so this function has no meaning. The YANG + compiler SHOULD return an empty string for this function. + + The "namespace-uri" and "name" functions SHOULD NOT be used. + Expanded names in XPath are different than YANG. A specific + canonical representation of a YANG-expanded name does not exist. + + The "lang" function SHOULD NOT be used. This function does not apply + to YANG because there is no "lang" attribute set with the document. + The YANG compiler SHOULD return 'false' for this function. + + + + + + +Bierman Best Current Practice [Page 21] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The "local-name", "namespace-uri", "name", "string", and "number" + functions SHOULD NOT be used if the argument is a node-set. If so, + the function result will be determined by the document order of the + node-set. Since this order can be different on each server, the + function results can also be different. Any function call that + implicitly converts a node-set to a string will also have this issue. + + The "local-name" function SHOULD NOT be used to reference local names + outside of the YANG module that defines the must or when expression + containing the "local-name" function. Example of a "local-name" + function that should not be used: + + /*[local-name()='foo'] + + The "derived-from-or-self" function SHOULD be used instead of an + equality expression for identityref values. This allows the + identities to be conceptually augmented. + + Example: + + // do not use + when "md-name-format = 'name-format-null'"; + + // this is preferred + when "derived-from-or-self(md-name-format, 'name-format-null')"; + +4.6.3. Axes + + The "attribute" and "namespace" axes are not supported in YANG and + MAY be empty in a NETCONF or RESTCONF server implementation. + + The "preceding" and "following" axes SHOULD NOT be used. These + constructs rely on XML document order within a NETCONF or RESTCONF + server configuration database, which may not be supported + consistently or produce reliable results across implementations. + Predicate expressions based on static node properties (e.g., element + name or value, and "ancestor" or "descendant" axes) SHOULD be used + instead. The "preceding" and "following" axes MAY be used if + document order is not relevant to the outcome of the expression + (e.g., check for global uniqueness of a parameter value). + + The "preceding-sibling" and "following-sibling" axes SHOULD NOT be + used; however, they MAY be used if document order is not relevant to + the outcome of the expression. + + + + + + + +Bierman Best Current Practice [Page 22] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + A server is only required to maintain the relative XML document order + of all instances of a particular user-ordered list or leaf-list. The + "preceding-sibling" and "following-sibling" axes MAY be used if they + are evaluated in a context where the context node is a user-ordered + "list" or "leaf-list". + +4.6.4. Types + + Data nodes that use the "int64" and "uint64" built-in type SHOULD NOT + be used within numeric or boolean expressions. There are boundary + conditions in which the translation from the YANG 64-bit type to an + XPath number can cause incorrect results. Specifically, an XPath + "double" precision floating-point number cannot represent very large + positive or negative 64-bit numbers because it only provides a total + precision of 53 bits. The "int64" and "uint64" data types MAY be + used in numeric expressions if the value can be represented with no + more than 53 bits of precision. + + Data modelers need to be careful not to confuse the YANG value space + and the XPath value space. The data types are not the same in both, + and conversion between YANG and XPath data types SHOULD be considered + carefully. + + Explicit XPath data type conversions MAY be used (e.g., "string", + "boolean", or "number" functions), instead of implicit XPath data + type conversions. + + XPath expressions that contain a literal value representing a YANG + identity SHOULD always include the declared prefix of the module + where the identity is defined. + + XPath expressions for "when" statements SHOULD NOT reference the + context node or any descendant nodes of the context node. They MAY + reference descendant nodes if the "when" statement is contained + within an "augment" statement, and the referenced nodes are not + defined within the "augment" statement. + + Example: + + augment "/rt:active-route/rt:input/rt:destination-address" { + when "rt:address-family='v4ur:ipv4-unicast'" { + description + "This augment is valid only for IPv4 unicast."; + } + // nodes defined here within the augment-stmt + // cannot be referenced in the when-stmt + } + + + + +Bierman Best Current Practice [Page 23] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.6.5. Wildcards + + It is possible to construct XPath expressions that will evaluate + differently when combined with several modules within a server + implementation rather than when evaluated within the single module. + This is due to augmenting nodes from other modules. + + Wildcard expansion is done within a server against all the nodes from + all namespaces, so it is possible for a "must" or "when" expression + that uses the '*' operator to always evaluate to false if processed + within a single YANG module. In such cases, the "description" + statement SHOULD clarify that augmenting objects are expected to + match the wildcard expansion. + + when /foo/services/*/active { + description + "No services directly defined in this module. + Matches objects that have augmented the services container."; + } + +4.6.6. Boolean Expressions + + The YANG "must" and "when" statements use an XPath boolean expression + to define the test condition for the statement. It is important to + specify these expressions in a way that will not cause inadvertent + changes in the result if the objects referenced in the expression are + updated in future revisions of the module. + + For example, the leaf "foo2" must exist if the leaf "foo1" is equal + to "one" or "three": + + leaf foo1 { + type enumeration { + enum one; + enum two; + enum three; + } + } + + leaf foo2 { + // INCORRECT + must "/f:foo1 != 'two'"; + type string; + } + + + + + + + +Bierman Best Current Practice [Page 24] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + leaf foo2 { + // CORRECT + must "/f:foo1 = 'one' or /f:foo1 = 'three'"; + type string; + } + + In the next revision of the module, leaf "foo1" is extended with a + new enum named "four": + + leaf foo1 { + type enumeration { + enum one; + enum two; + enum three; + enum four; + } + } + + Now the first XPath expression will allow the enum "four" to be + accepted in addition to the "one" and "three" enum values. + +4.7. YANG Definition Lifecycle Management + + The YANG status statement MUST be present within a definition if its + value is "deprecated" or "obsolete". The status SHOULD NOT be + changed from "current" directly to "obsolete". An object SHOULD be + available for at least one year with a "deprecated" status before it + is changed to "obsolete". + + The module or submodule name MUST NOT be changed, once the document + containing the module or submodule is published. + + The module namespace URI value MUST NOT be changed, once the document + containing the module is published. + + The revision date substatement within the import statement SHOULD be + present if any groupings are used from the external module. + + The revision date substatement within the include statement SHOULD be + present if any groupings are used from the external submodule. + + + + + + + + + + + +Bierman Best Current Practice [Page 25] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + If an import statement is for a module from a stable source (e.g., an + RFC for an IETF module), then a reference-stmt SHOULD be present + within an import statement. + + import ietf-yang-types { + prefix yang; + reference "RFC 6991: Common YANG Data Types"; + } + + If submodules are used, then the document containing the main module + MUST be updated so that the main module revision date is equal to or + more recent than the revision date of any submodule that is (directly + or indirectly) included by the main module. + + Definitions for future use SHOULD NOT be specified in a module. Do + not specify placeholder objects like the "reserved" example below: + + leaf reserved { + type string; + description + "This object has no purpose at this time, but a future + revision of this module might define a purpose + for this object."; + } + } + +4.8. Module Header, Meta, and Revision Statements + + For published modules, the namespace MUST be a globally unique URI, + as defined in [RFC3986]. This value is usually assigned by the IANA. + + The "organization" statement MUST be present. If the module is + contained in a document intended for IETF Standards Track status, + then the organization SHOULD be the IETF working group (WG) chartered + to write the document. For other standards organizations, a similar + approach is also suggested. + + The "contact" statement MUST be present. If the module is contained + in a document intended for Standards Track status, then the WG web + and mailing information SHOULD 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. There is no need to include the contact information for WG + Chairs. + + The "description" statement MUST be present. For modules published + within IETF documents, the appropriate IETF Trust Copyright text MUST + be present, as described in Section 3.1. + + + +Bierman Best Current Practice [Page 26] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + If the module relies on information contained in other documents, + which are not the same documents implied by the import statements + present in the module, then these documents MUST be identified in the + reference statement. + + A "revision" statement MUST be present for each published version of + the module. The "revision" statement MUST have a "reference" + substatement. It MUST identify the published document that contains + the module. Modules are often extracted from their original + documents, and it is useful for developers and operators to know how + to find the original source document in a consistent manner. The + "revision" statement MAY have a "description" substatement. + + The following example shows the revision statement for a published + YANG module: + + revision "2012-02-22" { + description + "Initial version"; + reference + "RFC 8341: Network Configuration + Access Control Model"; + } + + For an unpublished module, a complete history of each unpublished + module revision is not required. That is, within a sequence of draft + versions, only the most recent revision need be recorded in the + module. Do not remove or reuse a revision statement for a published + module. A new revision date is not required unless the module + contents have changed. If the module contents have changed, then the + revision date of that new module version MUST be updated to a date + later than that of the previous version. + + + + + + + + + + + + + + + + + + + +Bierman Best Current Practice [Page 27] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The following example shows the two revision statements for an + unpublished update to a published YANG module: + + revision "2017-12-11" { + description + "Added support for YANG 1.1 actions and notifications tied to + data nodes. Clarify how NACM extensions can be used by other + data models."; + reference + "RFC 8407: Network Configuration Protocol (NETCONF) + Access Control Model"; + } + + revision "2012-02-22" { + description + "Initial version"; + reference + "RFC 8341: Network Configuration + Access Control Model"; + } + +4.9. Namespace Assignments + + It is RECOMMENDED that only valid YANG modules be included in + documents, whether or not the modules are published yet. This + allows: + + o the module to compile correctly instead of generating disruptive + fatal errors. + + o early implementors to use the modules without picking a random + value for the XML namespace. + + o early interoperability testing since independent implementations + will use the same XML namespace value. + + Until a URI is assigned by the IANA, a proposed namespace URI MUST be + provided for the namespace statement in a YANG module. A value + SHOULD be selected that is not likely to collide with other YANG + namespaces. Standard module names, prefixes, and URI strings already + listed in the "YANG Module Names" registry MUST NOT be used. + + A standard namespace statement value SHOULD have the following form: + + : + + + + + + +Bierman Best Current Practice [Page 28] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The following URN prefix string SHOULD be used for published and + unpublished YANG modules: + + urn:ietf:params:xml:ns:yang: + + The following example URNs would be valid namespace statement values + for Standards Track modules: + + urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock + + urn:ietf:params:xml:ns:yang:ietf-netconf-state + + urn:ietf:params:xml:ns:yang:ietf-netconf + + Note that a different URN prefix string SHOULD be used for modules + that are not Standards Track. The string SHOULD be selected + according to the guidelines in [RFC7950]. + + The following URIs exemplify what might be used by modules that are + not Standards Track. Note that the domain "example.com" SHOULD be + used by example modules in IETF I-Ds. These URIs are not intended to + be dereferenced. They are used for module namespace identification + only. + + Example URIs using URLs per [RFC3986]: + + https://example.com/ns/example-interfaces + + https://example.com/ns/example-system + + Example URIs using tags per [RFC4151]: + + tag:example.com,2017:example-interfaces + + tag:example.com,2017:example-system + +4.10. Top-Level Data Definitions + + The top-level data organization SHOULD be considered carefully, in + advance. Data model designers need to consider how the functionality + for a given protocol or protocol family will grow over time. + + 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. Refer to NMDA [RFC8342] for details. + + + +Bierman Best Current Practice [Page 29] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The number of top-level data nodes within a module SHOULD be + minimized. It is often useful to retrieve related information within + a single subtree. If data is too distributed, it becomes difficult + to retrieve all at once. + + The names and data organization SHOULD reflect persistent + information, such as the name of a protocol. The name of the working + group SHOULD NOT be used because this may change over time. + + A mandatory database data definition is defined as a node that a + client must provide for the database to be valid. The server is not + required to provide a value. + + Top-level database data definitions MUST NOT be mandatory. If a + mandatory node appears at the top level, it will immediately cause + the database to be invalid. This can occur when the server boots or + when a module is loaded dynamically at runtime. + +4.11. Data Types + + Selection of an appropriate data type (i.e., built-in type, existing + derived type, or new derived type) is very subjective; therefore, few + requirements can be specified on that subject. + + Data model designers SHOULD use the most appropriate built-in data + type for the particular application. + + The signed numeric data types (i.e., "int8", "int16", "int32", and + "int64") SHOULD NOT be used unless negative values are allowed for + the desired semantics. + +4.11.1. Fixed-Value Extensibility + + If the set of values is fixed and the data type contents are + controlled by a single naming authority, then an enumeration data + type SHOULD be used. + + leaf foo { + type enumeration { + enum one; + enum two; + } + } + + If extensibility of enumerated values is required, then the + "identityref" data type SHOULD be used instead of an enumeration or + other built-in type. + + + + +Bierman Best Current Practice [Page 30] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + identity foo-type { + description "Base for the extensible type"; + } + + identity one { + base f:foo-type; + } + identity two { + base f:foo-type; + } + + leaf foo { + type identityref { + base f:foo-type; + } + } + + Note that any module can declare an identity with base "foo-type" + that is valid for the "foo" leaf. Identityref values are considered + to be qualified names. + +4.11.2. Patterns and Ranges + + For string data types, if a machine-readable pattern can be defined + for the desired semantics, then one or more pattern statements SHOULD + be present. A single-quoted string SHOULD be used to specify the + pattern, since a double-quoted string can modify the content. If the + patterns used in a type definition have known limitations such as + false negative or false positive matches, then these limitations + SHOULD be documented within the typedef or data definition. + + The following typedef from [RFC6991] demonstrates the proper use of + the "pattern" statement: + + typedef ipv4-address-no-zone { + type inet:ipv4-address { + pattern '[0-9\.]*'; + } + ... + } + + For string data types, if the length of the string is required to be + bounded in all implementations, then a length statement MUST be + present. + + + + + + + +Bierman Best Current Practice [Page 31] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The following typedef from [RFC6991] demonstrates the proper use of + the "length" statement: + + typedef yang-identifier { + type string { + length "1..max"; + pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; + pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; + } + ... + } + + For numeric data types, if the values allowed by the intended + semantics are different than those allowed by the unbounded intrinsic + data type (e.g., "int32"), then a range statement SHOULD be present. + + The following typedef from [RFC6991] demonstrates the proper use of + the "range" statement: + + typedef dscp { + type uint8 { + range "0..63"; + } + ... + } + +4.11.3. Enumerations and Bits + + For "enumeration" or "bits" data types, the semantics for each "enum" + or "bit" SHOULD be documented. A separate "description" statement + (within each "enum" or "bit" statement) SHOULD be present. + + leaf foo { + // INCORRECT + type enumeration { + enum one; + enum two; + } + description + "The foo enum... + one: The first enum + two: The second enum"; + } + + + + + + + + +Bierman Best Current Practice [Page 32] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + leaf foo { + // CORRECT + type enumeration { + enum one { + description "The first enum"; + } + enum two { + description "The second enum"; + } + } + description + "The foo enum... "; + } + +4.11.4. Union Types + + The YANG "union" type is evaluated by testing a value against each + member type in the union. The first type definition that accepts a + value as valid is the member type used. In general, member types + SHOULD be ordered from most restrictive to least restrictive types. + + In the following example, the "enumeration" type will never be + matched because the preceding "string" type will match everything. + + Incorrect: + + type union { + type string; + type enumeration { + enum up; + enum down; + } + } + + Correct: + + type union { + type enumeration { + enum up; + enum down; + } + type string; + } + + It is possible for different member types to match, depending on the + input encoding format. In XML, all values are passed as string + nodes; but in JSON, there are different value types for numbers, + booleans, and strings. + + + +Bierman Best Current Practice [Page 33] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + In the following example, a JSON numeric value will always be matched + by the "int32" type, but in XML the string value representing a + number will be matched by the "string" type. The second version will + match the "int32" member type no matter how the input is encoded. + + Incorrect: + + type union { + type string; + type int32; + } + + Correct: + + type union { + type int32; + type string; + } + +4.11.5. Empty and Boolean + + YANG provides an "empty" data type, which has one value (i.e., + present). The default is "not present", which is not actually a + value. When used within a list key, only one value can (and must) + exist for this key leaf. The type "empty" SHOULD NOT be used for a + key leaf since it is pointless. + + There is really no difference between a leaf of type "empty" and a + leaf-list of type "empty". Both are limited to one instance. The + type "empty" SHOULD NOT be used for a leaf-list. + + The advantage of using type "empty" instead of type "boolean" is that + the default (not present) does not take up any bytes in a + representation. The disadvantage is that the client may not be sure + if an empty leaf is missing because it was filtered somehow or not + implemented. The client may not have a complete and accurate schema + for the data returned by the server and may not be aware of the + missing leaf. + + The YANG "boolean" data type provides two values ("true" and + "false"). When used within a list key, two entries can exist for + this key leaf. Default values are ignored for key leafs, but a + default statement is often used for plain boolean leafs. The + advantage of the "boolean" type is that the leaf or leaf-list has a + clear representation for both values. The default value is usually + not returned unless explicitly requested by the client, so no bytes + are used in a typical representation. + + + + +Bierman Best Current Practice [Page 34] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + In general, the "boolean" data type SHOULD be used instead of the + "empty" data type, as shown in the example below: + + Incorrect: + + leaf flag1 { + type empty; + } + + Correct: + + leaf flag2 { + type boolean; + default false; + } + +4.12. Reusable Type Definitions + + If an appropriate derived type exists in any standard module, such as + [RFC6991], then it SHOULD be used instead of defining a new derived + type. + + If an appropriate units identifier can be associated with the desired + semantics, then a units statement SHOULD be present. + + If an appropriate default value can be associated with the desired + semantics, then a default statement SHOULD be present. + + If a significant number of derived types are defined, and it is + anticipated that these data types will be reused by multiple modules, + then these derived types SHOULD be contained in a separate module or + submodule, to allow easier reuse without unnecessary coupling. + + The "description" statement MUST be present. + + If the type definition semantics are defined in an external document + (other than another YANG module indicated by an import statement), + then the reference statement MUST be present. + +4.13. Reusable Groupings + + A reusable grouping is a YANG grouping that can be imported by + another module and is intended for use by other modules. This is not + the same as a grouping that is used within the module in which it is + defined, but it happens to be exportable to another module because it + is defined at the top level of the YANG module. + + + + + +Bierman Best Current Practice [Page 35] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The following guidelines apply to reusable groupings, in order to + make them as robust as possible: + + o Clearly identify the purpose of the grouping in the "description" + statement. + + o There are five different XPath contexts in YANG (rpc/input, rpc/ + output, notification, "config true" data nodes, and all data + nodes). Clearly identify which XPath contexts are applicable or + excluded for the grouping. + + o Do not reference data outside the grouping in any "path", "must", + or "when" statements. + + o Do not include a "default" substatement on a leaf or choice unless + the value applies on all possible contexts. + + o Do not include a "config" substatement on a data node unless the + value applies on all possible contexts. + + o Clearly identify any external dependencies in the grouping + "description" statement, such as nodes referenced by an absolute + path from a "path", "must", or "when" statement. + +4.14. Data Definitions + + The "description" statement MUST be present in the following YANG + statements: + + o anyxml + + o augment + + o choice + + o container + + o extension + + o feature + + o grouping + + o identity + + o leaf + + o leaf-list + + + +Bierman Best Current Practice [Page 36] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + o list + + o notification + + o rpc + + o typedef + + If the data definition semantics are defined in an external document, + (other than another YANG module indicated by an import statement), + then a reference statement MUST be present. + + The "anyxml" construct may be useful to represent an HTML banner + containing markup elements, such as "" and "", and MAY be used + in such cases. However, this construct SHOULD NOT be used if other + YANG data node types can be used instead to represent the desired + syntax and semantics. + + It has been found that the "anyxml" statement is not implemented + consistently across all servers. It is possible that mixed-mode XML + will not be supported or that configuration anyxml nodes will not + supported. + + If there are referential integrity constraints associated with the + desired semantics that can be represented with XPath, then one or + more "must" statements SHOULD be present. + + For list and leaf-list data definitions, if the number of possible + instances is required to be bounded for all implementations, then the + max-elements statements SHOULD be present. + + If any "must" or "when" statements are used within the data + definition, then the data definition "description" statement SHOULD + describe the purpose of each one. + + The "choice" statement is allowed to be directly present within a + "case" statement in YANG 1.1. This needs to be considered carefully. + Consider simply including the nested "choice" as additional "case" + statements within the parent "choice" statement. Note that the + "mandatory" and "default" statements within a nested "choice" + statement only apply if the "case" containing the nested "choice" + statement is first selected. + + If a list defines any key leafs, then these leafs SHOULD be defined + in order, as the first child nodes within the list. The key leafs + MAY be in a different order in some cases, e.g., they are defined in + a grouping, and not inline in the list statement. + + + + +Bierman Best Current Practice [Page 37] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.14.1. Non-Presence Containers + + A non-presence container is used to organize data into specific + subtrees. It is not intended to have semantics within the data model + beyond this purpose, although YANG allows it (e.g., a "must" + statement within the non-presence container). + + Example using container wrappers: + + container top { + container foos { + list foo { ... } + } + container bars { + list bar { ... } + } + } + + Example without container wrappers: + + container top { + list foo { ... } + list bar { ... } + } + + Use of non-presence containers to organize data is a subjective + matter similar to use of subdirectories in a file system. Although + these containers do not have any semantics, they can impact protocol + operations for the descendant data nodes within a non-presence + container, so use of these containers SHOULD be considered carefully. + + The NETCONF and RESTCONF protocols do not currently support the + ability to delete all list (or leaf-list) entries at once. This + deficiency is sometimes avoided by use of a parent container (i.e., + deleting the container also removes all child entries). + +4.14.2. Top-Level Data Nodes + + Use of top-level objects needs to be considered carefully: + + o top-level siblings are not ordered + + o top-level siblings are not static and depend on the modules that + are loaded + + + + + + + +Bierman Best Current Practice [Page 38] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + o for subtree filtering, retrieval of a top-level leaf-list will be + treated as a content-match node for all top-level-siblings + + o a top-level list with many instances may impact performance + +4.15. Operation Definitions + + If the operation semantics are defined in an external document (other + than another YANG module indicated by an import statement), then a + reference statement MUST be present. + + If the operation impacts system behavior in some way, it SHOULD be + mentioned in the "description" statement. + + If the operation is potentially harmful to system behavior in some + way, it MUST be mentioned in the Security Considerations section of + the document. + +4.16. Notification Definitions + + The "description" statement MUST be present. + + If the notification semantics are defined in an external document + (other than another YANG module indicated by an import statement), + then a reference statement MUST be present. + + If the notification refers to a specific resource instance, then this + instance SHOULD be identified in the notification data. This is + usually done by including "leafref" leaf nodes with the key leaf + values for the resource instance. For example: + + notification interface-up { + description "Sent when an interface is activated."; + leaf name { + type leafref { + path "/if:interfaces/if:interface/if:name"; + } + } + } + + Note that there are no formal YANG statements to identify any data + node resources associated with a notification. The "description" + statement for the notification SHOULD specify if and how the + notification identifies any data node resources associated with the + specific event. + + + + + + +Bierman Best Current Practice [Page 39] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.17. Feature Definitions + + 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 associated with a YANG feature, + then consider moving those objects to a separate module, instead of + using a YANG feature. Note that the set of features within a module + is easily discovered by the reader, but the set of related modules + within the entire YANG library is not as easy to identity. Module + names with a common prefix can help readers identity the set of + related modules, but this assumes the reader will have discovered and + installed all the relevant modules. + + Another consideration for deciding whether to create a new module or + add a YANG feature is the stability of the module in question. It + may be desirable to have a stable base module that is not changed + frequently. If new functionality is placed in a separate module, + then the base module does not need to be republished. If it is + designed as a YANG feature, then the module will need to be + republished. + + If one feature requires implementation of another feature, then an + "if-feature" statement SHOULD be used in the dependent "feature" + statement. + + For example, feature2 requires implementation of feature1: + + feature feature1 { + description "Some protocol feature"; + } + + feature feature2 { + if-feature "feature1"; + description "Another protocol feature"; + } + + + + + + +Bierman Best Current Practice [Page 40] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.18. YANG Data Node Constraints + +4.18.1. Controlling Quantity + + The "min-elements" and "max-elements" statements can be used to + control how many list or leaf-list instances are required for a + particular data node. YANG constraint statements SHOULD be used to + identify conditions that apply to all implementations of the data + model. If platform-specific limitations (e.g., the "max-elements" + supported for a particular list) are relevant to operations, then a + data model definition statement (e.g., "max-ports" leaf) SHOULD be + used to identify the limit. + +4.18.2. "must" versus "when" + + "must" and "when" YANG statements are used to provide cross-object + referential tests. They have very different behavior. The "when" + statement causes data node instances to be silently deleted as soon + as the condition becomes false. A false "when" expression is not + considered to be an error. + + The "when" statement SHOULD be used together with "augment" or "uses" + statements to achieve conditional model composition. The condition + SHOULD be based on static properties of the augmented entry (e.g., + list key leafs). + + The "must" statement causes a datastore validation error if the + condition is false. This statement SHOULD be used for enforcing + parameter value restrictions that involve more than one data node + (e.g., end-time parameter must be after the start-time parameter). + +4.19. "augment" Statements + + The YANG "augment" statement is used to define a set of data + definition statements that will be added as child nodes of a target + data node. The module namespace for these data nodes will be the + augmenting module, not the augmented module. + + A top-level "augment" statement SHOULD NOT be used if the target data + node is in the same module or submodule as the evaluated "augment" + statement. The data definition statements SHOULD be added inline + instead. + +4.19.1. Conditional Augment Statements + + The "augment" statement is often used together with the "when" + statement and/or "if-feature" statement to make the augmentation + conditional on some portion of the data model. + + + +Bierman Best Current Practice [Page 41] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The following example from [RFC7223] shows how a conditional + container called "ethernet" is added to the "interface" list only for + entries of the type "ethernetCsmacd". + + augment "/if:interfaces/if:interface" { + when "if:type = 'ianaift:ethernetCsmacd'"; + + container ethernet { + leaf duplex { + ... + } + } + } + +4.19.2. Conditionally Mandatory Data Definition Statements + + YANG has very specific rules about how configuration data can be + updated in new releases of a module. These rules allow an "old + client" to continue interoperating with a "new server". + + If data nodes are added to an existing entry, the old client MUST NOT + be required to provide any mandatory parameters that were not in the + original module definition. + + It is possible to add conditional "augment" statements such that the + old client would not know about the new condition and would not + specify the new condition. The conditional "augment" statement can + contain mandatory objects only if the condition is false, unless + explicitly requested by the client. + + Only a conditional "augment" statement that uses the "when" statement + form of a condition can be used in this manner. The YANG features + enabled on the server cannot be controlled by the client in any way, + so it is not safe to add mandatory augmenting data nodes based on the + "if-feature" statement. + + The XPath "when" statement condition MUST NOT reference data outside + of the target data node because the client does not have any control + over this external data. + + In the following dummy example, it is okay to augment the "interface" + entry with "mandatory-leaf" because the augmentation depends on + support for "some-new-iftype". The old client does not know about + this type, so it would never select this type; therefore, it would + not add a mandatory data node. + + + + + + +Bierman Best Current Practice [Page 42] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + module example-module { + + yang-version 1.1; + namespace "tag:example.com,2017:example-module"; + prefix mymod; + + import iana-if-type { prefix iana; } + import ietf-interfaces { prefix if; } + + identity some-new-iftype { + base iana:iana-interface-type; + } + + augment "/if:interfaces/if:interface" { + when "if:type = 'mymod:some-new-iftype'"; + + leaf mandatory-leaf { + type string; + mandatory true; + } + } + } + + Note that this practice is safe only for creating data resources. It + is not safe for replacing or modifying resources if the client does + not know about the new condition. The YANG data model MUST be + packaged in a way that requires the client to be aware of the + mandatory data nodes if it is aware of the condition for this data. + In the example above, the "some-new-iftype" identity is defined in + the same module as the "mandatory-leaf" data definition statement. + + This practice is not safe for identities defined in a common module + such as "iana-if-type" because the client is not required to know + about "my-module" just because it knows about the "iana-if-type" + module. + +4.20. Deviation Statements + + Per RFC 7950, Section 7.20.3, the YANG "deviation" statement is not + allowed to appear in IETF YANG modules, but it can be useful for + documenting server capabilities. Deviation statements are not + reusable and typically not shared across all platforms. + + There are several reasons that deviations might be needed in an + implementation, e.g., an object cannot be supported on all platforms, + or feature delivery is done in multiple development phases. + Deviation statements can also be used to add annotations to a module, + which does not affect the conformance requirements for the module. + + + +Bierman Best Current Practice [Page 43] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + It is suggested that deviation statements be defined in separate + modules from regular YANG definitions. This allows the deviations to + be platform specific and/or temporary. + + The order that deviation statements are evaluated can affect the + result. Therefore, multiple deviation statements in the same module, + for the same target object, SHOULD NOT be used. + + The "max-elements" statement is intended to describe an architectural + limit to the number of list entries. It is not intended to describe + platform limitations. It is better to use a "deviation" statement + for the platforms that have a hard resource limit. + + Example documenting platform resource limits: + + Wrong: (max-elements in the list itself) + + container backups { + list backup { + ... + max-elements 10; + ... + } + } + + Correct: (max-elements in a deviation) + + deviation /bk:backups/bk:backup { + deviate add { + max-elements 10; + } + } + +4.21. Extension Statements + + The YANG "extension" statement is used to specify external + definitions. This appears in the YANG syntax as an + "unknown-statement". Usage of extension statements in a published + module needs to be considered carefully. + + The following guidelines apply to the usage of YANG extensions: + + o The semantics of the extension MUST NOT contradict any YANG + statements. Extensions can add semantics not covered by the + normal YANG statements. + + + + + + +Bierman Best Current Practice [Page 44] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + o The module containing the extension statement MUST clearly + identify the conformance requirements for the extension. It + should be clear whether all implementations of the YANG module + containing the extension need to also implement the extension. If + not, identify what conditions apply that would require + implementation of the extension. + + o The extension MUST clearly identify where it can be used within + other YANG statements. + + o The extension MUST clearly identify if YANG statements or other + extensions are allowed or required within the extension as + substatements. + +4.22. Data Correlation + + Data can be correlated in various ways, using common data types, + common data naming, and common data organization. There are several + ways to extend the functionality of a module, based on the degree of + coupling between the old and new functionality: + + o inline: update the module with new protocol-accessible objects. + The naming and data organization of the original objects is used. + The new objects are in the original module namespace. + + o augment: create a new module with new protocol-accessible objects + that augment the original data structure. The naming and data + organization of the original objects is used. The new objects are + in the new module namespace. + + o mirror: create new objects in a new module or the original module, + except use a new naming scheme and data location. The naming can + be coupled in different ways. Tight coupling is achieved with a + "leafref" data type, with the "require-instance" substatement set + to "true". This method SHOULD be used. + + If the new data instances are not limited to the values in use in the + original data structure, then the "require-instance" substatement + MUST be set to "false". Loose coupling is achieved by using key + leafs with the same data type as the original data structure. This + has the same semantics as setting the "require-instance" substatement + to "false". + + The relationship between configuration and operational state has been + clarified in NMDA [RFC8342]. + + + + + + +Bierman Best Current Practice [Page 45] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.22.1. Use of "leafref" for Key Correlation + + Sometimes it is not practical to augment a data structure. For + example, the correlated data could have different keys or contain + mandatory nodes. + + The following example shows the use of the "leafref" data type for + data correlation purposes: + + Not preferred: + + list foo { + key name; + leaf name { + type string; + } + ... + } + + list foo-addon { + key name; + config false; + leaf name { + type string; + } + ... + } + + Preferred: + + list foo { + key name; + leaf name { + type string; + } + ... + } + + list foo-addon { + key name; + config false; + leaf name { + type leafref { + path "/foo/name"; + require-instance false; + } + } + leaf addon { + + + +Bierman Best Current Practice [Page 46] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + type string; + mandatory true; + } + } + +4.23. Operational State + + The modeling of operational state with YANG has been refined over + time. At first, only data that has a "config" statement value of + "false" was considered to be operational state. This data was not + considered to be part of any datastore, which made the YANG XPath + definition much more complicated. + + Operational state is now modeled using YANG according to the new NMDA + [RFC8342] and conceptually contained in the operational state + datastore, which also includes the operational values of + configuration data. There is no longer any need to duplicate data + structures to provide separate configuration and operational state + sections. + + This section describes some data modeling issues related to + operational state and guidelines for transitioning YANG data model + design to be NMDA compatible. + +4.23.1. Combining Operational State and Configuration Data + + If possible, operational state SHOULD be combined with its associated + configuration data. This prevents duplication of key leafs and + ancestor nodes. It also prevents race conditions for retrieval of + dynamic entries and allows configuration and operational state to be + retrieved together with minimal message overhead. + + container foo { + ... + // contains "config true" and "config false" nodes that have + // no corresponding "config true" object (e.g., counters) + } + +4.23.2. Representing Operational Values of Configuration Data + + If possible, the same data type SHOULD be used to represent the + configured value and the operational value, for a given leaf or leaf- + list object. + + Sometimes the configured value set is different than the operational + value set for that object, for example, the "admin-status" and + "oper-status" leafs in [RFC8343]. In this case, a separate object + MAY be used to represent the configured and operational values. + + + +Bierman Best Current Practice [Page 47] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + Sometimes the list keys are not identical for configuration data and + the corresponding operational state. In this case, separate lists + MAY be used to represent the configured and operational values. + + If it is not possible to combine configuration and operational state, + then the keys used to represent list entries SHOULD be the same type. + The "leafref" data type SHOULD be used in operational state for key + leafs that have corresponding configuration instances. The + "require-instance" statement MAY be set to "false" (in YANG 1.1 + modules only) to indicate instances are allowed in the operational + state that do not exist in the associated configuration data. + + The need to replicate objects or define different operational state + objects depends on the data model. It is not possible to define one + approach that will be optimal for all data models. + + Designers SHOULD describe and justify any NMDA exceptions in detail, + such as the use of separate subtrees and/or separate leafs. The + "description" statements for both the configuration and the + operational state SHOULD be used for this purpose. + +4.23.3. NMDA Transition Guidelines + + YANG modules SHOULD be designed with the assumption that they will be + used on servers supporting the operational state datastore. With + this in mind, YANG modules SHOULD define "config false" nodes + wherever they make sense to the data model. "Config false" nodes + SHOULD NOT be defined to provide the operational value for + configuration nodes, except when the value space of a configured and + operational value may differ, in which case a distinct "config false" + node SHOULD be defined to hold the operational value for the + configured node. + + The following guidelines are meant to help modelers develop YANG + modules that will maximize the utility of the model with both current + and new implementations. + + New modules and modules that are not concerned with the operational + state of configuration information SHOULD immediately be structured + to be NMDA compatible, as described in Section 4.23.1. This + transition MAY be deferred if the module does not contain any + configuration datastore objects. + + + + + + + + + +Bierman Best Current Practice [Page 48] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The remaining are options that MAY be followed during the time that + NMDA mechanisms are being defined. + + (a) Modules that require immediate support for the NMDA features + SHOULD be structured for NMDA. A temporary non-NMDA version of + this type of module MAY exist, as either an existing model or a + model created by hand or with suitable tools that mirror the + current modeling strategies. Both the NMDA and the non-NMDA + modules SHOULD be published in the same document, with NMDA + modules in the document main body and the non-NMDA modules in a + non-normative appendix. The use of the non-NMDA module will + allow temporary bridging of the time period until NMDA + implementations are available. + + (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] has been + restructured as an NMDA-compatible model in [RFC8343]. The + "/interfaces-state" hierarchy has been marked "status + deprecated". Models that mark their "/foo-state" hierarchy with + "status deprecated" will allow NMDA-capable implementations to + avoid the cost of duplicating the state nodes, while enabling + non-NMDA-capable implementations to utilize them for access to + the operational values. + + (c) For models that augment models that have not been structured + with the NMDA, the modeler will have to consider the structure + of the base model and the guidelines listed above. Where + possible, such models should move to new revisions of the base + model that are NMDA compatible. When that is not possible, + augmenting "state" containers SHOULD be avoided, with the + expectation that the base model will be re-released with the + state containers marked as deprecated. It is RECOMMENDED to + augment only the "/foo" hierarchy of the base model. Where this + recommendation cannot be followed, then any new "state" elements + SHOULD be included in their own module. + +4.23.3.1. Temporary Non-NMDA Modules + + A temporary non-NMDA module allows a non-NMDA-aware client to access + operational state from an NMDA-compliant server. It contains the + top-level "config false" data nodes that would have been defined in a + legacy YANG module (before NMDA). + + A server that needs to support both NMDA and non-NMDA clients can + advertise both the new NMDA module and the temporary non-NMDA module. + A non-NMDA client can use separate "foo" and "foo-state" subtrees, + except the "foo-state" subtree is located in a different (temporary) + + + +Bierman Best Current Practice [Page 49] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + module. The NMDA module can be used by a non-NMDA client to access + the conventional configuration datastores and the deprecated + operation to access nested "config false" data nodes. + + To create the temporary non-NMDA model from an NMDA model, the + following steps can be taken: + + o Change the module name by appending "-state" to the original + module name + + o Change the namespace by appending "-state" to the original + namespace value + + o Change the prefix by appending "-s" to the original prefix value + + o Add an import to the original module (e.g., for typedef + definitions) + + o Retain or create only the top-level nodes that have a "config" + statement value "false". These subtrees represent "config false" + data nodes that were combined into the configuration subtree; + therefore, they are not available to non-NMDA aware clients. Set + the "status" statement to "deprecated" for each new node. + + o The module description SHOULD clearly identify the module as a + temporary non-NMDA module + +4.23.3.2. Example: Create a New NMDA Module + + Create an NMDA-compliant module, using combined configuration and + state subtrees, whenever possible. + + module example-foo { + namespace "urn:example.com:params:xml:ns:yang:example-foo"; + prefix "foo"; + + container foo { + // configuration data child nodes + // operational value in operational state datastore only + // may contain "config false" nodes as needed + } + } + + + + + + + + + +Bierman Best Current Practice [Page 50] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.23.3.3. Example: Convert an Old Non-NMDA Module + + Do not remove non-compliant objects from existing modules. Instead, + change the status to "deprecated". At some point, usually after 1 + year, the status MAY be changed to "obsolete". + + Old Module: + + module example-foo { + namespace "urn:example.com:params:xml:ns:yang:example-foo"; + prefix "foo"; + + container foo { + // configuration data child nodes + } + + container foo-state { + config false; + // operational state child nodes + } + } + + Converted NMDA Module: + + module example-foo { + namespace "urn:example.com:params:xml:ns:yang:example-foo"; + prefix "foo"; + + container foo { + // configuration data child nodes + // operational value in operational state datastore only + // may contain "config false" nodes as needed + // will contain any data nodes from old foo-state + } + + // keep original foo-state but change status to deprecated + container foo-state { + config false; + status deprecated; + // operational state child nodes + } + } + + + + + + + + + +Bierman Best Current Practice [Page 51] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.23.3.4. Example: Create a Temporary NMDA Module + + Create a new module that contains the top-level operational state + data nodes that would have been available before they were combined + with configuration data nodes (to be NMDA compliant). + + module example-foo-state { + namespace "urn:example.com:params:xml:ns:yang:example-foo-state"; + prefix "foo-s"; + + // import new or converted module; not used in this example + import example-foo { prefix foo; } + + container foo-state { + config false; + status deprecated; + // operational state child nodes + } + } + +4.24. Performance Considerations + + It is generally likely that certain YANG statements require more + runtime resources than other statements. Although there are no + performance requirements for YANG validation, the following + information MAY be considered when designing YANG data models: + + o Lists are generally more expensive than containers + + o "when" statement evaluation is generally more expensive than + "if-feature" or "choice" statements + + o "must" statements are generally more expensive than "min-entries", + "max-entries", "mandatory", or "unique" statements + + o "identityref" leafs are generally more expensive than + "enumeration" leafs + + o "leafref" and "instance-identifier" types with "require-instance" + set to true are generally more expensive than if + "require-instance" is set to false + +4.25. Open Systems Considerations + + Only the modules imported by a particular module can be assumed to be + present in an implementation. An open system MAY include any + combination of YANG modules. + + + + +Bierman Best Current Practice [Page 52] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +4.26. Guidelines for Constructs Specific to YANG 1.1 + + The set of guidelines for YANG 1.1 will grow as operational + experience is gained with the new language features. This section + contains an initial set of guidelines for new YANG 1.1 language + features. + +4.26.1. Importing Multiple Revisions + + Standard modules SHOULD NOT import multiple revisions of the same + module into a module. This MAY be done if independent definitions + (e.g., enumeration typedefs) from specific revisions are needed in + the importing module. + +4.26.2. Using Feature Logic + + The YANG 1.1 feature logic is much more expressive than YANG 1.0. A + "description" statement SHOULD describe the "if-feature" logic in + text, to help readers understand the module. + + YANG features SHOULD be used instead of the "when" statement, if + possible. Features are advertised by the server, and objects + conditional by the "if-feature" statement are conceptually grouped + together. There is no such commonality supported for "when" + statements. + + Features generally require less server implementation complexity and + runtime resources than objects that use "when" statements. Features + are generally static (i.e., set when a module is loaded and not + changed at runtime). However, every client edit might cause a "when" + statement result to change. + +4.26.3. "anyxml" versus "anydata" + + The "anyxml" statement MUST NOT be used to represent a conceptual + subtree of YANG data nodes. The "anydata" statement MUST be used for + this purpose. + +4.26.4. "action" versus "rpc" + + The use of "action" statements or "rpc" statements is a subjective + design decision. RPC operations are not associated with any + particular data node. Actions are associated with a specific data + node definition. An "action" statement SHOULD be used if the + protocol operation is specific to a subset of all data nodes instead + of all possible data nodes. + + + + + +Bierman Best Current Practice [Page 53] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + The same action name MAY be used in different definitions within + different data node. For example, a "reset" action defined with a + data node definition for an interface might have different parameters + than for a power supply or a VLAN. The same action name SHOULD be + used to represent similar semantics. + + The NETCONF Access Control Model (NACM) [RFC8341] does not support + parameter-based access control for RPC operations. The user is given + permission (or not) to invoke the RPC operation with any parameters. + For example, if each client is only allowed to reset their own + interface, then NACM cannot be used. + + For example, NACM cannot enforce access control based on the value of + the "interface" parameter, only the "reset" operation itself: + + rpc reset { + input { + leaf interface { + type if:interface-ref; + mandatory true; + description "The interface to reset."; + } + } + } + + However, NACM can enforce access control for individual interface + instances, using a "reset" action. If the user does not have read + access to the specific "interface" instance, then it cannot invoke + the "reset" action for that interface instance: + + container interfaces { + list interface { + ... + action reset { } + } + } + +4.27. Updating YANG Modules (Published versus Unpublished) + + YANG modules can change over time. Typically, new data model + definitions are needed to support new features. YANG update rules + defined in Section 11 of [RFC7950] MUST be followed for published + modules. They MAY be followed for unpublished modules. + + The YANG update rules only apply to published module revisions. Each + organization will have their own way to identify published work that + is considered to be stable and unpublished work that is considered to + + + + +Bierman Best Current Practice [Page 54] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + be unstable. For example, in the IETF, the RFC document is used for + published work, and the I-D is used for unpublished work. + +5. IANA Considerations + + The following registration in the "ns" subregistry of the "IETF XML + Registry" [RFC3688] was detailed in [RFC6087] and has been updated by + IANA to reference this document. + + URI: urn:ietf:params:xml:ns:yang:ietf-template + + Registrant Contact: The IESG. + + XML: N/A, the requested URI is an XML namespace. + + The following assignment was detailed in [RFC6087] and has been + updated by IANA in the "YANG Module Names" registry. This document + has also been added as a reference for the "YANG Module Names" + registry itself as it contains the template necessary for + registration in Appendix B. + + +-----------+-------------------------------------------+ + | Field | Value | + +-----------+-------------------------------------------+ + | Name | ietf-template | + | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | + | Prefix | temp | + | Reference | RFC 8407 | + +-----------+-------------------------------------------+ + + YANG Registry Assignment + +6. Security Considerations + + This document defines documentation guidelines for NETCONF or + RESTCONF content defined with the YANG data modeling language; + therefore, it does not introduce any new or increased security risks + into the management system. + + + + + + + + + + + + + +Bierman Best Current Practice [Page 55] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +7. References + +7.1. Normative References + + [ID-Guidelines] + Housley, R., "Guidelines to Authors of Internet-Drafts", + December 2010, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + DOI 10.17487/RFC3688, January 2004, + . + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + . + + [RFC5378] Bradner, S., Ed. and J. Contreras, Ed., "Rights + Contributors Provide to the IETF Trust", BCP 78, RFC 5378, + DOI 10.17487/RFC5378, November 2008, + . + + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + DOI 10.17487/RFC6020, October 2010, + . + + [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., + and A. Bierman, Ed., "Network Configuration Protocol + (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, + . + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, + . + + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", + RFC 7950, DOI 10.17487/RFC7950, August 2016, + . + + + + + + +Bierman Best Current Practice [Page 56] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF + Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., + and R. Wilton, "Network Management Datastore Architecture + (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, + . + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + + [W3C.REC-xpath] + Clark, J. and S. DeRose, "XML Path Language (XPath) + Version 1.0", W3C Recommendation REC-xpath-19991116, + November 1999, + . + +7.2. Informative References + + [IANA-MOD-NAMES] + IANA, "YANG Module Names", + . + + [IANA-XML] IANA, "IETF XML Registry", + . + + [RFC-STYLE] + RFC Editor, "Style Guide", + . + + [RFC2026] Bradner, S., "The Internet Standards Process -- Revision + 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, + . + + [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", + RFC 4151, DOI 10.17487/RFC4151, October 2005, + . + + [RFC4181] Heard, C., Ed., "Guidelines for Authors and Reviewers of + MIB Documents", BCP 111, RFC 4181, DOI 10.17487/RFC4181, + September 2005, . + + + + +Bierman Best Current Practice [Page 57] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG + Data Model Documents", RFC 6087, DOI 10.17487/RFC6087, + January 2011, . + + [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", + RFC 6991, DOI 10.17487/RFC6991, July 2013, + . + + [RFC7223] Bjorklund, M., "A YANG Data Model for Interface + Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, + . + + [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, + DOI 10.17487/RFC7322, September 2014, + . + + [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., + "RFC Streams, Headers, and Boilerplates", RFC 7841, + DOI 10.17487/RFC7841, May 2016, + . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", + BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, + . + + [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration + Access Control Model", STD 91, RFC 8341, + DOI 10.17487/RFC8341, March 2018, + . + + [RFC8343] Bjorklund, M., "A YANG Data Model for Interface + Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, + . + + [RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for + Routing Management (NMDA Version)", RFC 8349, + DOI 10.17487/RFC8349, March 2018, + . + + + + + + + + +Bierman Best Current Practice [Page 58] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +Appendix A. Module Review Checklist + + This section is adapted from RFC 4181. + + The purpose of a YANG module review is to review the YANG module for + both technical correctness and adherence to IETF documentation + requirements. The following checklist may be helpful when reviewing + an I-D: + + o I-D Boilerplate -- verify that the document contains the required + I-D boilerplate (see ), including the appropriate statement to permit + publication as an RFC, and that the I-D boilerplate does not + contain references or section numbers. + + o Abstract -- verify that the abstract does not contain references, + that it does not have a section number, and that its content + follows the guidelines in . + + o Copyright Notice -- verify that the document has the appropriate + text regarding the rights that document contributors provide to + the IETF Trust [RFC5378]. Verify that it contains the full IETF + Trust copyright notice at the beginning of the document. The IETF + Trust Legal Provisions (TLP) can be found at: + + + + o Security Considerations section -- verify that the document uses + the latest approved template from the Operations and Management + (OPS) area website (see ) and that the guidelines therein have + been followed. + + o IANA Considerations section -- this section must always be + present. For each module within the document, ensure that the + IANA Considerations section contains entries for the following + IANA registries: + + XML Namespace Registry: Register the YANG module namespace. + + YANG Module Registry: Register the YANG module name, prefix, + namespace, and RFC number, according to the rules specified in + [RFC6020]. + + + + + + + +Bierman Best Current Practice [Page 59] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + o References -- verify that the references are properly divided + between normative and informative references, that RFCs 2119 and + 8174 are included as normative references if the terminology + defined therein is used in the document, that all references + required by the boilerplate are present, that all YANG modules + containing imported items are cited as normative references, and + that all citations point to the most current RFCs, unless there is + a valid reason to do otherwise (for example, it is okay to include + an informative reference to a previous version of a specification + to help explain a feature included for backward compatibility). + Be sure citations for all imported modules are present somewhere + in the document text (outside the YANG module). If a YANG module + contains reference or "description" statements that refer to an + I-D, then the I-D is included as an informative reference. + + o License -- verify that the document contains the Simplified BSD + License in each YANG module or submodule. Some guidelines related + to this requirement are described in Section 3.1. Make sure that + the correct year is used in all copyright dates. Use the approved + text from the latest TLP document, which can be found at: + + + + o Other Issues -- check for any issues mentioned in + that are not covered + elsewhere. + + o Technical Content -- review the actual technical content for + compliance with the guidelines in this document. The use of a + YANG module compiler is recommended when checking for syntax + errors. A list of freely available tools and other information, + including formatting advice, can be found at: + + + and + + + Checking for correct syntax, however, is only part of the job. + It is just as important to actually read the YANG module document + from the point of view of a potential implementor. It is + particularly important to check that "description" statements are + sufficiently clear and unambiguous to allow interoperable + implementations to be created. + + + + + + + + +Bierman Best Current Practice [Page 60] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +Appendix B. YANG Module Template + + file "ietf-template@2016-03-20.yang" + + module ietf-template { + yang-version 1.1; + + // replace this string with a unique namespace URN value + + namespace "urn:ietf:params:xml:ns:yang:ietf-template"; + + // replace this string, and try to pick a unique prefix + + prefix temp; + + // import statements here: e.g., + // import ietf-yang-types { prefix yang; } + // import ietf-inet-types { prefix inet; } + // identify the IETF working group if applicable + + organization + "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; + + // update this contact statement with your info + + contact + "WG Web: + WG List: + + Editor: your-name + "; + + // replace the first sentence in this description statement. + // replace the copyright notice with the most recent + // version, if it has been updated since the publication + // of this document + + description + "This module defines a template for other YANG modules. + + Copyright (c) IETF Trust and the persons + identified as authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, with or + without modification, is permitted pursuant to, and subject + to the license terms contained in, the Simplified BSD License + set forth in Section 4.c of the IETF Trust's Legal Provisions + + + + +Bierman Best Current Practice [Page 61] + +RFC 8407 Guidelines for YANG Documents October 2018 + + + Relating to IETF Documents + (http://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC XXXX; see + the RFC itself for full legal notices."; + + // RFC Ed.: replace XXXX with actual RFC number and remove + // this note + + // replace '2016-03-20' with the module publication date + // the format is (year-month-day) + + revision 2016-03-20 { + description + "what changed in this revision"; + reference "RFC XXXX: "; + } + + // extension statements + // feature statements + // identity statements + // typedef statements + // grouping statements + // data definition statements + // augment statements + // rpc statements + // notification statements + // DO NOT put deviation statements in a published module + } + + + +Acknowledgments + + The structure and contents of this document are adapted from + "Guidelines for Authors and Reviewers of MIB Documents" [RFC4181], by + C. M. Heard. + + The working group thanks Martin Bjorklund, Juergen Schoenwaelder, + Ladislav Lhotka, Jernej Tuljak, Lou Berger, Robert Wilton, Kent + Watsen, and William Lupton for their extensive reviews and + contributions to this document. + + + + + + + + + +Bierman Best Current Practice [Page 62] + +RFC 8407 Guidelines for YANG Documents October 2018 + + +Author's Address + + Andy Bierman + YumaWorks + + Email: andy@yumaworks.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Bierman Best Current Practice [Page 63] + -- cgit v1.2.3