RFC 9907
Guidelines for Authors and Reviewers of Documents Containing YANG Data Models
RFC 9907: Guidelines for Authors and Reviewers of Documents Containing YANG Data Models โจ
Okay bestie, this is an IETF document (Internet Engineering Task Force) and it's RFC 9907 ๐ฆ It's a Best Current Practice (that's BCP 216), published in March 2026, with ISSN 2070-1721. Three authors wrote it: A. Bierman from YumaWorks, M. Boucadair (the "Ed." means editor ๐ ) from Orange, and Q. Wu from Huawei. It obsoletes RFC 8407, so this replaces that older guide, and it updates RFC 8126, which means it adds new guidance on top of that one ๐ธ
Abstract โจ
This document gives guidelines for authors and reviewers of specs that contain YANG data models, including IANA-maintained YANG modules ๐ It defines recommendations and procedures meant to make NETCONF and RESTCONF implementations that use YANG modules more interoperable and easier to use ๐
It obsoletes RFC 8407. It also updates RFC 8126 by adding extra guidelines for writing the IANA considerations for RFCs that specify IANA-maintained YANG modules ๐
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 had public review and has been approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on BCPs, check out Section 2 of RFC 7841 ๐ฅ
Info about the current status of this document, any errata, and how to send feedback on it is at https://www.rfc-editor.org/info/rfc9907 ๐ซถ
Copyright Notice
Copyright (c) 2026 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) as they stand on the date this document was published. Please read these carefully, because they describe your rights and restrictions for this document ๐ Code Components pulled out of this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Revised BSD License ๐
Table of Contents
1. Introduction
1.1. Changes Since RFC 8407
2. Terminology and Notation Conventions
2.1. NETCONF Terms
2.2. YANG Terms
2.3. Network Management Datastore Architecture (NMDA) Terms
2.4. Requirements Notation
2.5. YANG Data Model versus YANG Module
3. General Documentation Guidelines
3.1. Module Copyright
3.2. Code Components
3.2.1. Example Modules
3.3. Terminology Section
3.4. Tree Diagrams
3.5. Narrative Sections
3.5.1. YANG Module Classification
3.6. Definitions Section
3.7. Security Considerations Section
3.7.1. Security Considerations Section Template
3.8. IANA Considerations Section
3.8.1. Documents That Create a New Namespace
3.8.2. Documents That Extend an Existing Namespace
3.8.3. Registration Templates
3.9. References Sections
3.10. Validation Tools
3.11. Module Extraction Tools
3.12. Module Usage Examples
4. YANG Usage Guidelines
4.1. Module Naming Conventions
4.2. Prefixes
4.3. Identifiers
4.3.1. Identifier Naming Conventions
4.4. Defaults
4.5. Conditional Statements
4.6. XPath Usage
4.6.1. XPath Evaluation Contexts
4.6.2. Function Library
4.6.3. Axes
4.6.4. Types
4.6.5. Wildcards
4.6.6. Boolean Expressions
4.7. YANG Definition Lifecycle Management
4.8. Module Header, Meta, and Revision Statements
4.9. Namespace Assignments
4.10. Top-Level Data Definitions
4.11. Data Types
4.11.1. Fixed-Value Extensibility
4.11.2. Patterns and Ranges
4.11.3. Enumerations and Bits
4.11.4. Union Types
4.11.5. Empty and Boolean
4.12. Reusable Type Definitions
4.13. Reusable Groupings
4.14. Data Definitions
4.14.1. Non-Presence Containers
4.14.2. Top-Level Data Nodes
4.15. Operation Definitions
4.16. Notification Definitions
4.17. Feature Definitions
4.18. YANG Data Node Constraints
4.18.1. Controlling Quantity
4.18.2. "must" versus "when"
4.19. "augment" Statements
4.19.1. Conditional Augment Statements
4.19.2. Conditionally Mandatory Data Definition Statements
4.20. Deviation Statements
4.21. Extension Statements
4.22. Data Correlation
4.22.1. Use of "leafref" for Key Correlation
4.23. Operational State
4.23.1. Combining Operational State and Configuration Data
4.23.2. Representing Operational Values of Configuration Data
4.23.3. NMDA Transition Guidelines
4.24. Performance Considerations
4.25. Open Systems Considerations
4.26. Guidelines for Constructs Specific to YANG 1.1
4.26.1. Importing Multiple Revisions
4.26.2. Using Feature Logic
4.26.3. "anyxml" versus "anydata"
4.26.4. "action" versus "rpc"
4.27. Updating YANG Modules (Published versus Unpublished)
4.28. Defining Standard Tags
4.29. Modeling Abstract Data Structures
4.30. IANA-Maintained YANG Modules
4.30.1. Context
4.30.2. Guidelines for IANA-Maintained YANG Modules
4.30.3. Guidance for Writing the IANA Considerations for RFCs
Defining IANA-Maintained YANG Modules
5. IANA Considerations
5.1. YANG Modules
5.2. Update in YANG Parameters Registry Group
5.3. IANA-Maintained YANG Modules
5.3.1. Requirements for All Modules
5.3.2. Requirements Subject to Customization
6. Operational Considerations
7. Security Considerations
8. References
8.1. Normative References
8.2. Informative References
Appendix A. Module Review Checklist
Appendix B. Template for IETF Modules
Appendix C. Template for IANA-Maintained YANG Modules
Acknowledgments
Authors' Addresses1. Introduction โจ
Network configuration interfaces that work with configuration management protocols like NETCONF [RFC6241] and RESTCONF [RFC8040] need a modular set of data models ๐ง They have to be reusable and extendable over time, so the whole thing doesn't fall apart as the Internet grows ๐ธ
This document defines a set of guidelines for documents that contain YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models, including IANA-maintained YANG modules ๐ YANG is used to define data structures, protocol operations, and notification content inside a NETCONF and/or RESTCONF server. It's also used to define abstract data structures [RFC8791] ๐ฆ A NETCONF or RESTCONF server that supports a particular YANG module will support client NETCONF and/or RESTCONF operation requests, as shown by the specific content the YANG module defines ๐
Lots of YANG constructs are optional to use, like the description statement. Still, to make YANG modules more readable and interoperable, it's a good idea to have a set of descriptive usage guidelines that asks for a higher level of compliance than the minimum that the YANG specification [RFC7950] sets ๐
YANG also allows things like infinite-length identifiers and string values, or top-level mandatory nodes, that a compliant server doesn't have to support. So only constructs that every server is 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 to the RESTCONF methods and RESTCONF resources, as defined in [RFC8040] ๐
These guidelines are meant for authors and reviewers to improve the readability and interoperability of published YANG data models. They can be used independently of the IETF Stream of publication, or even by other organizations ๐
YANG 1.0 modules have to conform to [RFC6020], and YANG 1.1 modules have to conform to [RFC7950]. This document adds usage guidelines on top of these RFCs โจ
Section 4.30.3 updates [RFC8126] by giving guidance for writing the IANA Considerations sections for RFCs that specify IANA-maintained YANG modules ๐
Heads up: this document is not a YANG tutorial. The reader is expected to already know the YANG data modeling language before putting the guidance here into practice ๐
This RFC contains text meant to be used as a template, marked as shown below by <BEGIN TEMPLATE TEXT> and <END TEMPLATE TEXT>, or by some other clear designation. That Template Text is subject to the provisions of Section 9(b) of the Trust Legal Provisions ๐ซถ
Part 1 of 17 is done! More parts are coming, so don't leave me hanging ๐
1.1. Changes Since RFC 8407
Okay bestie, here's the glow-up tea ๐ Everything that changed from [RFC8407] is below, and it's a LOT:
- Squashed the bugs from these errata reports: [Err5693], [Err5800], [Err6899], and [Err7416]. ๐
- Refreshed the terminology ๐
- Dropped in a note about notation conventions ๐
- Updated the reference info for the IETF author guidelines ๐
- Made the "file name" after the
<CODE BEGINS>tag mandatory, no skipping ๐ซถ - Added template markers for the security template ๐
- Beefed up the YANG security considerations template so it really insists on the key secure transport features ๐
- Added statements that the security template is not required for modules that follow [RFC8791] or define YANG extensions such as [RFC7952] ๐
- Added a statement about how to cite the RFCs listed in the security template ๐
- Added a template for IANA registrations ๐ฆ
- Added a note that folding of the examples should be done as per the conventions described in [RFC8792] โ๏ธ
- Added a recommendation about long trees ๐ณ
- Fixed a reference bug in Section 4.1 ๐ ๏ธ
- Added a recommendation for the use of meaningful prefix values ๐
- Added a note that folding of YANG modules as described in RFC 8792 can be used if and only if built-in YANG features (e.g., break line, "+") are not sufficient ๐งต
- Added tool validation checks to make sure YANG modules fit into the line limits of an I-D ๐
- Added tool validation checks of JSON-encoded examples ๐งพ
- Added a recommendation to ease extracting and validating examples ๐ง
- Updated many examples to match the consistent indentation recommendation (internal consistency) ๐
- Updated the IANA Considerations guidance so registration requests indicate whether or not a module is maintained by IANA ๐
- Added guidelines for IANA-maintained YANG modules ๐๏ธ
- Added guidelines about the use of the terms "YANG module" and "YANG data model" ๐ฃ๏ธ
- Elaborated the guidance for the use of values reserved for documentation in examples ๐
- Recommended the use of "example:" for URI examples ๐
- Added a new section "Defining Standard Tags" (Section 4.28) to echo the guidance in [RFC8819] ๐ท๏ธ
- Recommended against the use of "case + when" construct in some cases ๐ โโ๏ธ
- Added a discussion about the prefix pattern to use for example modules ๐จ
- Updated the NMDA guidance in the narrative text to highlight modules that are not compliant with NMDA ๐
- Added a new section about the classification of YANG modules ๐๏ธ
- Fixed an inconsistency in Section 4.6.2 where the example mentions identities but uses them without their prefix as per Section 4.6.4 ๐งฉ
- Fixed an inconsistency in Section 4.6.4 that failed to use "derived-from-or-self()" mentioned back in Section 4.6.2 ๐ง
- Added a new section for modeling abstract data structures ๐งฑ
- Added a discussion about "must + error-message" constructs for state data ๐ฌ
- Added text about summary of changes in "revision" statements ๐
- Added a template for IANA-maintained YANG modules ๐
- Updated the wiki URLs to use the new structure ๐
- Added "anydata" to the list of statements with mandatory description(s) (Section 4.14) โ
- Fixed an error (invalid statements) in Section 4.24 ๐ฉน
- Softened the generic I-D authorship guidance ๐ซง
2. Terminology and Notation Conventions โจ
Some of the templates in this document use -- to flag instructions for the authors. Text prefixed with -- must not be copied as such when you use a template. For YANG templates, // is used to carry those instructions instead.
RFC IIII is used to refer to an RFC that defines an initial version of an IANA-maintained YANG module.
These terms are used all over the place in this document:
- IANA-maintained YANG module: A YANG module that IANA maintains and that has an IANA registry attached to it (for example, "iana-tunnel-type" [RFC8675] or "iana-pseudowire-types" [RFC9291]). Once an IANA-maintained YANG module is initialized, new values don't get added straight to the module. They go into the companion registry instead. ๐ท๏ธ
- IETF module: A YANG module that is published by the IETF and that is not maintained by IANA. ๐ข
- published: A stable release of a module or submodule. For example, the Request for Comments Series described in Section 2.1 of [RFC2026] is considered a stable publication. โ
- 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 work in progress, subject to change at any time. ๐ง
- YANG fragment: A set of YANG statements that isn't meant to be a complete YANG module or submodule. These statements aren't for actual use, except as an example of YANG statement usage. The invalid syntax
...is sometimes used to show that more YANG statements would be present in a real YANG module. ๐งฉ - YANG tree diagram: A diagram showing the contents of a YANG module, as defined in [RFC8340]. It is also called a "tree diagram". ๐ฒ
2.1. NETCONF Terms
These terms are defined in [RFC6241] and aren't redefined here:
- capability
- client
- protocol operation (or simply "operation")
- server
2.2. YANG Terms
These terms are defined in [RFC7950] and aren't redefined here:
- data node
- module
- namespace
- submodule
- version
- YANG
- YIN
The term "module" can 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. Network Management Datastore Architecture (NMDA) Terms
These terms are defined in [RFC8342] and aren't redefined here:
- configuration
- conventional configuration datastore
- datastore
- operational state
- 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. ๐
2.5. YANG Data Model versus YANG Module
Both [RFC6020] and [RFC7950] make a distinction between these two concepts, and so do we ๐
- data model: Describes how data is represented and accessed. YANG structures data models into modules for ease of use [RFC8309].
- module: Defines hierarchies of schema nodes to make a self-contained and compilable block of YANG definitions and inclusions.
A YANG module is typically a single ".yang" file, starting with a module statement.
A YANG module may include any number of submodules that are stored in separate ".yang" files starting with a submodule statement. Regardless of whether submodules are present, the module and its submodules are externally viewed as a single YANG module. ๐ช
A YANG data model can consist of:
Note that the term "YANG model" is sometimes used as an abbreviation of "YANG data model". However, that term should be avoided in favor of "YANG data model". Likewise, "YANG data module" has no meaning and must be avoided. ๐
Even if a YANG data model is structured as a single YANG module, the term "YANG data model" should be used in the title, abstract, and in the body of the document where the overall design is described. "YANG module" should be used when a specific "*.yang" file is referenced. Likewise, "YANG module" should be used when using terms related to YANG module specifications (e.g., augmentation or deviation). However, when extending the concepts embodied in a YANG module, authors should refer to those as an extension to the "YANG data model". ๐
3. General Documentation Guidelines ๐งพ
YANG modules being considered for publication in an RFC live in Internet-Drafts (I-Ds). You can find guidelines for authoring an I-D at [ID-Guidelines]. Those guidelines aren't repeated here.
The following sections MUST be present in an I-D or RFC containing a YANG module:
- Narrative sections (Section 3.5)
- A Definitions section(s) (Section 3.6)
Additional YANG-specific considerations MUST be included for the following sections:
- Security Considerations (Section 3.7)
- IANA Considerations (Section 3.8)
- References (Section 3.9)
There are three usage scenarios for YANG that can appear in an I-D or RFC:
- normative module or submodule
- example module or submodule
- example YANG fragment that is not part of any module or submodule
The guidelines in this document mainly refer to a normative module or submodule, but they may be applicable to example modules and YANG fragments as well. ๐ธ
3.1. Module Copyright
The module "description" statement MUST contain a reference to the latest approved IETF Trust Copyright statement, which is available at: <https://trustee.ietf.org/license-info/>. ยฉ๏ธ
3.2. Code Components
Each normative YANG module or submodule contained within an I-D or RFC is considered to be a code component. The strings "<CODE BEGINS>" and "<CODE ENDS>" MUST be used to identify each code component. ๐งฉ
The "<CODE BEGINS>" tag MUST be followed by a string identifying the file name specified in Section 5.2 of [RFC7950]. The name string form that includes the revision date SHOULD be used. The revision date MUST match the date used in the most recent revision of the module. ๐
The following example is for the "2016-03-20" revision of the "ietf-foo" module:
<CODE BEGINS>
file "ietf-foo@2016-03-20.yang"
module ietf-foo {
namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
prefix "foo";
organization "...";
contact "...";
description "...";
revision 2016-03-20 {
description "Latest revision";
reference "RFC FFFF: Foo Protocol";
}
// ... more statements
}
<CODE ENDS>3.2.1. Example Modules
Example modules are not code components. The "<CODE BEGINS>" convention MUST NOT be used for example modules. However, example modules MUST be validated (Section 3.10). ๐งช
An example module SHOULD be named using the term "example", followed by a hyphen, followed by a descriptive name, e.g., "example-toaster". ๐
See Section 4.9 regarding the namespace guidelines for example modules. ๐
3.3. Terminology Section
A terminology section MUST be present if any terms are defined in the document or if any terms are imported from other documents. ๐
3.4. Tree Diagrams
YANG tree diagrams give 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]. Tree diagrams longer than one page SHOULD be included in an appendix, i.e., not in the main body of the document. ๐ณ
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 ๐
Okay so the narrative sections MUST include an overview section ๐ธ that describes the scope and field of application of the data model(s) defined by the specification. It also has to say how those data models relate (if they do at all) to other standards, especially standards with their own YANG data models โจ. The narrative part SHOULD include one or more sections that briefly describe the structure of the data models defined in the specification ๐ง.
If the module (or modules) defined by the specification imports definitions from other modules, except those defined in [RFC7950] or [RFC9911], or is always implemented alongside 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 major Network Management Datastore Architecture (NMDA) exceptions or includes a temporary non-NMDA module [RFC8342], then the Introduction section SHOULD mention this fact, along with the reasoning behind that design ๐ฆ. Refer to Section 4.23 for more NMDA-related guidance. Section 4.23.2 specifically includes a recommendation for designers to describe and justify any NMDA exceptions in detail as part of the module itself ๐.
Consistent indentation SHOULD be used for all examples, including YANG fragments and protocol message instance data โจ. If line wrapping is used for formatting purposes, then this SHOULD be indicated per the guidance in [RFC8792], as shown in the following example ๐:
=============== NOTE: '\' line wrapping per RFC 8792 ================
<myleaf xmlns="tag:example.com,2017:example-two">this is a long \
value so the line needs to wrap to stay within 72 characters</myleaf>Built-in YANG features (e.g., breaking line, "+") SHOULD be used to fit a module into the line limits ๐. Exceptionally, YANG modules MAY be folded as described in RFC 8792 if and only if built-in YANG features are not sufficient ๐ซถ. A similar approach SHOULD be followed for tree diagrams, such as using --tree-line-length 69 or splitting a tree into subtrees ๐งฉ.
3.5.1. YANG Module Classification ๐ท๏ธ
The narrative section SHOULD include a mention of the classification of a given model. This helps position the module in the overall operational ecosystem ๐บ๏ธ. Specifically, the following types from [RFC8309] and [RFC8969] can be used:
- Service Model: Describes a service and the parameters of the service in a portable way that can be used uniformly and independent of the equipment and operating environment ๐ผ.
- Network Model: Describes a network-level abstraction (or a subset of aspects of a network infrastructure), including devices and their subsystems, and relevant protocols operating at the link and network layers across multiple devices ๐. This model corresponds to the network configuration model discussed in [RFC8309].
- This model can be used by a network operator to allocate resources (e.g., a tunnel resource or a topology resource) for the service, or to schedule resources to meet the service requirements defined in a service model ๐ฆ.
- Examples of network models are the L3VPN Network Model (L3NM) [RFC9182] or the L2VPN Network Model (L2NM) [RFC9291] ๐.
- Device Model: Refers to the Network Element YANG data model described in [RFC8199] or the device configuration model discussed in [RFC8309] ๐.
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 YANG Independent Notation (YIN) syntax version (Section 13 of [RFC7950]) 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), and those 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] applies to YANG "description" statements in normative modules exactly as it would in any other normative section ๐.
Example YANG modules and example YANG fragments MUST NOT contain any normative text, including any key words from [RFC2119] and [RFC8174] ๐ โโ๏ธ.
Consistent indentation and formatting (e.g., folding) 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 ๐ก๏ธ. Dramatic, but true: this part is serious business ๐ญ.
Unless the modules comply with [RFC8791] or define YANG extensions (e.g., [RFC7952]), the security section MUST be modeled after the latest approved template, which is available at <https://wiki.ietf.org/group/ops/yang-security-guidelines>. Section 3.7.1 contains the security considerations template ๐. Authors MUST check the web page at the URL listed above in case there is a more recent version available ๐.
In particular:
- Writable data nodes that could be especially disruptive if abused MUST be explicitly listed by name, and the security risks that come with them MUST be explained ๐ฅ.
- 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 ๐.
- Operations (i.e., YANG
rpcstatements) 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 ๐จ.
Documents that exclusively define modules that follow the extension in [RFC8791] are not required to include the security template in Section 3.7.1 ๐ท. Likewise, following the template is not required for modules that define YANG extensions such as [RFC7952] ๐ฆ.
3.7.1. Security Considerations Section Template ๐
Okay bestie, here's the copy-paste template for your Security Considerations section. Fill in the <module-name> and the X. bits, and keep the wording exactly as it is ๐
<BEGIN TEMPLATE TEXT>
X. Security Considerations
This section is modeled after the template described in Section 3.7.1
of [RFC9907].
The "<module-name>" YANG module defines a data model that is
designed to be accessed via YANG-based management protocols,
such as the Network Configuration Protocol (NETCONF) [RFC6241]
and RESTCONF [RFC8040]. These YANG-based management protocols
(1) have to use a secure transport layer (e.g., Secure Shell (SSH)
[RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use
mutual authentication.
The Network Configuration Access Control Model (NACM) [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.
-- Note: RFC 8341 (or a future RFC that replaces it) MUST be listed
-- as a normative reference.
-- By default, RFC 4252, RFC 6241, RFC 8040, RFC 8446, RFC 9000, and
-- RFC 9907 (or future RFCs that replace any of them) are listed as
-- informative references unless normatively cited in other sections
-- of the document that specifies the YANG module.
-- Writable nodes section:
--
-- If the data model contains any writable data nodes (those are all
-- the "config true" nodes), then include the following text:
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). All writable data nodes are likely to be sensitive or
vulnerable in some network environments. Write
operations (e.g., edit-config) and delete operations to these data
nodes without proper protection or authentication can have a negative
effect on network operations. The following subtrees and data nodes
have particular sensitivities/vulnerabilities:
-- If the data model contains any particularly sensitive data nodes,
-- e.g., ones that are protected by a "nacm:default-deny-write"
-- or a "nacm:default-deny-all" extensions statement, then those
-- subtrees and data nodes must be listed, with an explanation of the
-- associated security risks with a focus on how they can be
-- disruptive if abused. Otherwise, state:
--
-- "There are no particularly sensitive writable data nodes."
-- Readable nodes section:
--
-- If the data model contains any readable data nodes (i.e., those
-- that are "config false" nodes, but also all other nodes because
-- they can also be read via operations like get or get-config), then
-- include the following text:
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. Specifically, the following
subtrees and data nodes have particular sensitivities/
vulnerabilities:
-- You must evaluate whether the data model contains 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) that are particularly sensitive or vulnerable
-- (e.g., if they might reveal customer information or violate
-- personal privacy laws). Typically, particularly sensitive
-- readable data nodes are ones that are protected by a
-- "nacm:default-deny-read" or a "nacm:default-deny-all" extensions
-- statement.
--
-- Otherwise, state:
-- "There are no particularly sensitive readable data nodes."
-- RPC/action operations section:
--
-- If the data model contains any RPC or action operations, then
-- include the following text:
Some of the RPC or action 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.
Specifically, the following operations have particular
sensitivities/ vulnerabilities:
-- If the data model contains any particularly sensitive RPC
-- or action operations, then those operations must be listed
-- here, along with an explanation of the associated specific
-- sensitivity or vulnerability concerns.
--
-- Otherwise, state:
-- "There are no particularly sensitive RPC or action operations."
-- Reusable groupings from other modules section:
--
-- If the data model reuses groupings from other modules and
-- the document that specifies these groupings also
-- includes those as data nodes, then add this text as a
-- reminder of the specific sensitivity or vulnerability of
-- reused nodes.
This YANG module uses groupings from other YANG modules that
define nodes that may be considered sensitive or vulnerable
in network environments. Refer to the Security Considerations
of <RFC-insert-numbers> for information as to which nodes may
be considered sensitive or vulnerable in network environments.
-- No data nodes section:
--
-- If the data model does not define any data nodes (i.e., none
-- of the above sections or readable/writable data nodes or RPCs
-- have been included), then add the following text:
The YANG module defines a set of identities, types, and
groupings. These nodes are intended to be reused by other YANG
modules. The module by itself does not expose any data nodes that
are writable, data nodes that contain read-only state, or RPCs.
As such, there are no additional security issues related to
the YANG module that need to be considered.
Modules that use the groupings that are defined in this document
should identify the corresponding security considerations. For
example, reusing some of these groupings will expose privacy-related
information (e.g., 'node-example').
<END TEMPLATE TEXT>3.8. IANA Considerations Section ๐๏ธ
Okay, this is the IANA part, so put on your registry hat ๐ Every normative YANG module MUST be registered in both the "IETF XML Registry" group [RFC3688] [IANA-XML] and the "YANG Module Names" registry [RFC6020] [IANA-MOD-NAMES]. The registration request in the "YANG Module Names" registry should indicate whether or not the module is IANA-maintained. This applies to both new modules and updated modules. An example of an update registration for the ietf-template module can be found in Section 5.
Additional IANA considerations for IANA-maintained YANG modules (including instructions to maintain them) are in Section 4.30.3 โจ
3.8.1. Documents That Create a New Namespace
If an I-D defines a new namespace that is going to be administered by the IANA, then the document MUST include an IANA Considerations section that specifies how that namespace is to be administered ๐ธ
Specifically, if any YANG module namespace statement value in the document is not already registered with IANA, then a new entry in the "ns" registry within the "IETF XML Registry" registry group MUST be requested from the IANA.
A registration template for new YANG modules is in Section 3.8.3.1 ๐
3.8.2. Documents That Extend an Existing Namespace
It's possible to extend an existing namespace with 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.8.3. Registration Templates
3.8.3.1. IANA Template for Documents Defining New YANG Modules
A registration template for a new module is provided below:
IANA is requested to register the following URI in the "ns"
registry within the "IETF XML Registry" group [RFC3688]:
URI:
Registrant Contact: The IESG
XML: N/A; the requested URI is an XML namespace.
IANA is requested to register the following YANG module in the "YANG
Module Names" registry [RFC6020] within the "YANG Parameters"
registry group.
Name:
Maintained by IANA? Y/N
Namespace:
Prefix:
Reference:3.8.3.2. IANA Template for Revising YANG Modules
A registration template for a revised module is provided below:
IANA is requested to update the following registration in the "ns"
registry within the "IETF XML Registry" group [RFC3688] to
reference this document:
URI:
Registrant Contact: The IESG
XML: N/A; the requested URI is an XML namespace.
IANA is requested to register the following YANG module in the "YANG
Module Names" registry [RFC6020] [RFC9890] within the "YANG Parameters"
registry group.
Name:
Maintained by IANA? Y/N
Namespace:
Prefix:
Reference:3.9. References Sections ๐
For every import or include statement in a module contained in the specification that points to 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 in a module contained in the specification that points to 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 pointing to a separate document, a corresponding informative reference to that document MAY appear in the Informative References section โจ
3.10. Validation Tools ๐งช
Every module needs to be validated before it gets submitted in an I-D, so no skipping this step, bestie ๐
The 'pyang' YANG compiler is freely available from GitHub: <https://github.com/mbj4668/pyang>.
If the 'pyang' compiler is used to validate a normative module, then the "--ietf" command-line option MUST be used to identify any IETF guideline issues ๐
If the 'pyang' compiler is used to validate an example module, then the "--ietf" command-line option MAY be used to identify any IETF guideline issues.
To make sure a module fits into the line limits of an I-D, the following command should be used:
pyang -f yang --keep-comments --yang-line-length 69The 'yanglint' program is also freely available from GitHub: <https://github.com/CESNET/libyang>.
This tool can be used to validate "XPath" statements within YANG modules.
To check that JSON-encoded examples [RFC7951] comply with the target data models, programs such as 'yangson' or 'yanglint' should be used. Both programs are freely available from GitHub: <https://github.com/CZ-NIC/yangson> and <https://github.com/CESNET/libyang> ๐
3.11. Module Extraction Tools ๐ง
A version of 'rfcstrip' that will extract YANG modules from an I-D or RFC is freely available at: <https://github.com/mbj4668/rfcstrip> ๐ฆ
This tool can be used to verify that the "<CODE BEGINS>" and "<CODE ENDS>" tags are used correctly and that the normative YANG modules can be extracted correctly ๐ซถ
The 'xym' tool is freely available on GitHub and can be used to extract YANG modules from a document: <https://github.com/xym-tool/xym> ๐
3.12. Module Usage Examples โจ
okay bestie, every spec that defines one or more modules SHOULD come with usage examples ๐, either sprinkled throughout the doc or tucked into an appendix. That includes example instance document snippets in an encoding that fits (XML and/or JSON, e.g., ๐ ) to show how the YANG module(s) are meant to be used. Examples that are meant to illustrate a valid data instance MUST be validated (Section 3.10). Check out Section 3.10 for the tools that validate YANG modules and examples ๐งฐ. If you're using IP addresses or prefixes, use a mix of IPv4 and IPv6 addresses/prefixes, or IPv6 addresses/prefixes only, in your examples. That's the SHOULD move ๐.
some types (IP addresses, domain names, etc.) have values the IETF reserved just for documentation, so authors SHOULD use those reserved values in usage examples whenever these types show up ๐ฆ. Here are the reserved values:
- IPv4 and IPv6 addresses/prefixes reserved for documentation are defined in [RFC5737], [RFC3849], and [RFC9637].
- The Enterprise Number 32473 reserved for documentation use is defined in [RFC5612].
- Autonomous System Numbers (ASNs) reserved for documentation use are defined in [RFC5398].
- Reserved domain names for documentation are defined in [RFC2606].
URI examples SHOULD be prefixed with "example:" ๐.
to make examples easier to extract and validate, it is RECOMMENDED to use code markers ๐ท๏ธ bestie, trust me on this one.
4. YANG Usage Guidelines
Modules in IETF Standards Track specifications MUST comply with all syntactic and semantic requirements of YANG 1.1 [RFC7950]. Peep the exception for YANG 1.0 in Section 3.6 ๐. The guidelines in this section are meant to supplement the YANG specification [RFC7950], which sets the minimum set of conformance requirements ๐ .
to promote interoperability and build practices on past experience, the following sections set up usage guidelines for specific YANG constructs ๐ง.
only guidelines that clarify or restrict the minimum conformance requirements are included here. No extra fluff ๐.
A template for IETF modules is provided in Appendix B.
4.1. Module Naming Conventions
normative modules in Standards Track documents MUST be named according to the guidelines in the IANA Considerations section of [RFC6020] ๐.
a distinctive word or abbreviation (e.g., a protocol name or working group abbreviation) SHOULD be used in the module name โจ. If you're defining new stuff that extends one or more existing modules, then the same word or abbreviation should be reused, instead of making a brand new one ๐ซถ.
all published module names MUST be unique. For a YANG module published in an RFC, IANA guarantees that uniqueness (Section 14 of [RFC6020]) ๐. 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's suggested that you pick a stable module name prefix that represents the whole organization ๐ข. All normative YANG modules published by the IETF MUST begin with the prefix "ietf-" ๐. All IANA-maintained YANG modules MUST begin with the prefix "iana-" ๐ธ. Another standards organization, like the IEEE, might use the prefix "ieee-" for all of its YANG modules โญ.
once a module name is published, it MUST NOT be reused, even if the RFC containing the module gets reclassified to "Historic" status ๐. A module name can't be changed in YANG, and trying would count as a brand new module, not a name change ๐ โโ๏ธ.
4.2. Prefixes
all YANG definitions are scoped by the module that contains the definition being referenced ๐. This lets the same name show up in multiple modules, even when the names aren't unique, which is lowkey iconic. 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 ๐:
- Prefixes are never used for built-in data types and YANG keywords.
- A prefix MUST be used for any external statement (i.e., a statement defined with the YANG "extension" statement).
- The proper module prefix MUST be used for all identifiers imported from other modules.
- The proper module prefix MUST be used for all identifiers included from a submodule.
the following guidelines apply to prefix usage of the current (local) module ๐ :
- The local module prefix SHOULD be used instead of no prefix in all path expressions.
- The local module prefix MUST be used instead of no prefix in all "default" statements for an "identityref" or "instance-identifier" data type.
- The local module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module.
consistent with Section 7.1.4 of [RFC7950], the prefix a module defines SHOULD be used when that module is imported, unless there's a conflict โก.
prefix values SHOULD be short but meaningful to the intended user ๐ซ. Prefix values SHOULD NOT conflict with known modules that have been published before ๐ โโ๏ธ.
for convenience, prefix values of example modules SHOULD be prefixed with "ex" or similar patterns ๐ง. Doing this means readers can instantly spot the example parts in example modules or tree diagrams that mix example and standard modules ๐.
4.3. Identifiers
all YANG identifiers in published modules MUST be between 1 and 64 characters in length ๐. This covers 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 those characters. YANG doesn't permit any other characters in YANG identifiers, so no sneaky symbols ๐ซ.
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 ๐ณ.
list identifiers SHOULD be singular, with the surrounding container name plural ๐ท. Similarly, "leaf-list" identifiers SHOULD be singular ๐ฆ.
it's permissible to use common identifiers like "name" or "id" in data definition statements, especially if those 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 not change whether it's configuration data or state data, so don't even try it ๐. Only defined YANG statements or YANG "extension" statements can assign semantics in a machine-readable format in YANG ๐ฅ.
4.4. Defaults
in general, it's suggested that substatements holding very common default values SHOULD NOT be present ๐งผ. The substatements in Table 1 are commonly used with their default value, which would make the module difficult to read if they were used everywhere they're allowed ๐ญ.
+==============+===============+
| Statement | Default Value |
+==============+===============+
| config | true |
+--------------+---------------+
| mandatory | false |
+--------------+---------------+
| max-elements | unbounded |
+--------------+---------------+
| min-elements | 0 |
+--------------+---------------+
| ordered-by | system |
+--------------+---------------+
| status | current |
+--------------+---------------+
| yin-element | false |
+--------------+---------------+
Table 1: Statement DefaultsHey bestie, let me say one quick thing before we dive in. This turn gives me nothing I need to act on, so I'll just get on with the rewrite. Everything below is the actual RFC text you pasted, and it never tells me to do anything. The output has to stay a faithful spec, so keep every key word, section, and code block exactly as it is. ๐ซถ
4.5. Conditional Statements โจ
okay so a module can be split up in a few different ways using the if-feature and/or when statements ๐งฉ
data model designers, this one's for you bestie ๐ you have to think hard about ALL the modularity stuff, including when you use YANG conditional statements. no cap, it matters ๐ญ
so like, if a data definition is optional because it depends on whether the server supports a NETCONF or RESTCONF protocol capability, then you SHOULD define a YANG feature statement for it ๐ and then the defined feature SHOULD be used in the conditional if-feature statement that points at that optional data definition โจ
now 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 that data node ๐ฆ and if there are any conditional requirements for returning the data node in a notification payload or a 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 inside the data node or in one of its ancestors (if any) ๐
if any if-feature statements apply to a list node, then the SAME if-feature statements MUST apply to any key leaf nodes for that list ๐ธ and there MUST NOT be any if-feature statements on a key leaf that do not also apply to the parent list node. no sneaky stuff ๐
โโ๏ธ
there SHOULD NOT be any when statements applied to a key leaf node ๐
it's possible that a when statement on an ancestor node of a key leaf ends up with the exact same node-set result as the key leaf. in that case the when statement on the key leaf is redundant and SHOULD be avoided ๐
some modules use a "case + when" construct but still duplicate information (like when the when statements are constraining a single case in the choice, as in the example below) ๐ constructs with duplicated information SHOULD NOT be used. bye bye duplicates ๐
leaf type {
type enumeration {
enum a;
enum b;
enum c;
}
mandatory true;
}
choice type-choice {
case b {
container type-b {
when "../type = 'b'";
leaf foo {
type string;
}
}
}
case c {
container type-c {
when "../type = 'c'";
leaf bar {
mandatory true;
type string;
}
}
}
}the next example gets rid of the duplicated info ๐ง
leaf type {
type enumeration {
enum a;
enum b;
enum c;
}
mandatory true;
}
container type-b {
when "../type = 'b'";
leaf foo {
type string;
}
}
container type-c {
when "../type = 'c'";
leaf bar {
mandatory true;
type string;
}
}note that "case + when" is still useful when you want to express complementary modeling constraints ๐ check out this example:
leaf type {
type enumeration {
enum a;
enum b;
enum c;
}
}
choice second-type {
mandatory true;
case foo {
container foo {
presence "When present, indicates type foo";
leaf foo-attribute {
type string;
}
}
}
case b {
container bar {
when "../type = 'a' or ../type = 'b'";
presence "When present, indicates type bar";
leaf bar-attribute {
type string;
}
}
}
case c {
container baz {
when "../type = 'c'";
leaf baz-attribute {
mandatory true;
type string;
}
}
}
}ok this part is kinda deep but it's giving main character energy ๐ Section 8.1 of [RFC7950] has rules for constraints on state data, and it says a constraint MUST be true in a valid state data tree. BUT Section 5.3 of [RFC8342] softens that a bit by letting semantic constraints be violated in some situations, so anomalies can be spotted ๐ relaxing validation on state data is meant to show when the observed behavior of a managed entity differs from what was intended, and hopefully sets off corrective actions from a management system ๐ ๏ธ so from that angle, it is RECOMMENDED to avoid defining constraints on state data that would get in the way of a management system detecting abnormal behavior of a managed entity ๐ซง
4.6. XPath Usage ๐ฆ
this section is all about guidelines for using the XML Path Language (XPath) [W3C.REC-xpath] inside YANG modules ๐
4.6.1. XPath Evaluation Contexts ๐
YANG defines five separate contexts for evaluating XPath statements:
- The "running" datastore: the 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". ๐
- State data + the "running" datastore: the collection of all YANG data nodes. The document root is the conceptual container, which is the parent of all top-level data definition statements. โจ
- Notification: an event notification document. The document root is the notification element. ๐
- RPC Input: the document root is the conceptual "input" node, which is the parent of all RPC input parameter definitions. ๐ฅ
- RPC Output: the document root is the conceptual "output" node, which is the parent of all RPC output parameter definitions. ๐ค
note that these XPath contexts CANNOT be mixed ๐
โโ๏ธ (sorry, I mean: they 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's SO important to think about the XPath evaluation context for XPath expressions defined in groupings ๐ซถ an XPath expression defined in a grouping may not be portable, which means it can't be used in multiple contexts and still give proper results ๐ญ
if the XPath expressions in a grouping are meant for one particular context, then that 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 too (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 XPath execution environment 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 in YANG, and 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 XPath execution environment SHOULD return "false" for this function ๐
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 statement 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:
// assume "ex" is the prefix of the module where the identity
// name-format-null is defined
// do not use
when "md-name-format = 'name-format-null'";
// this is preferred
when "derived-from-or-self(md-name-format, 'ex: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., checking 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.
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 โจ
okay bestie, the int64 and uint64 types are giving SHOULD NOT vibes inside numeric or boolean expressions ๐. Why? The translation from a YANG 64-bit number to an XPath number can break at the edges. An XPath "double" only has 53 bits of precision, so really huge positive or negative 64-bit numbers can't be represented properly. These types MAY be used in numeric expressions if the value fits in no more than 53 bits of precision ๐ข.
Data modelers, pay attention ๐ซถ. The YANG value space and the XPath value space are NOT the same, and the data types don't match up between them. Converting between YANG and XPath types SHOULD be considered carefully ๐.
Explicit XPath data type conversions MAY be used (like the string, boolean, or number functions) instead of implicit ones ๐
.
Any XPath expression that has a literal value representing a YANG identity SHOULD always include the declared prefix of the module where that identity is defined ๐ธ.
Now for when statements, which are very picky ๐ค. They SHOULD NOT reference the context node or any of its descendant nodes. They MAY reference descendant nodes, but only if the when statement is inside an augment statement and the referenced nodes are NOT defined within that augment statement ๐ฆ.
Here's an example:
augment "/rt:active-route/rt:input/rt:destination-address" {
when "derived-from-or-self(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
}4.6.5. Wildcards ๐
so this one is a whole plot twist ๐ฌ. You can write XPath expressions that act totally different once several modules are combined inside one server implementation, compared to when they're evaluated inside a single module. That happens because modules can augment nodes from other modules.
The server expands wildcards against ALL the nodes from ALL namespaces. That means a must or when statement that uses the * operator could always evaluate to false when processed within a single YANG module ๐. When that happens, 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 their test condition ๐ง . It's super important to write these expressions so they DON'T cause sneaky changes in the result if the objects they reference get updated in future revisions of the module. Future-you will thank you ๐.
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;
}
leaf foo2 {
// CORRECT
must "/f:foo1 = 'one' or /f:foo1 = 'three'";
type string;
}Now the next revision of the module adds a new enum called "four" to leaf "foo1" ๐ฑ:
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
enum four;
}
}And just like that, the first XPath expression lets "four" in too, on top of "one" and "three" ๐ฅ. That's the trap!
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 straight from "current" to "obsolete" ๐ซ. An object SHOULD stay available for at least one year after the publication date with a "deprecated" status before it's changed to "obsolete" โณ.
The module or submodule name MUST NOT be changed once the document containing it is published ๐. Same energy for the module namespace URI: it 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 ๐งฉ. Likewise, the revision date substatement within the "include" statement SHOULD be present if any groupings are used from the external submodule ๐งฉ.
If an "import" statement points to a module from a stable source (like an RFC for an IETF module), then a reference statement SHOULD be present within that "import" statement ๐:
import ietf-yang-types {
prefix yang;
reference "RFC 9911: Common YANG Data Types";
}If submodules are used, the document containing the main module MUST be updated so the main module revision date is equal to or more recent than the revision date of any submodule that the main module includes, directly or indirectly ๐ .
Definitions meant for future use SHOULD NOT be specified in a module ๐ โโ๏ธ. Don't add placeholder objects like this "reserved" leaf, no matter how tempting it is ๐๏ธ:
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 in a document intended for IETF Standards Track status, the organization SHOULD be the IETF working group (WG) chartered to write that document. The exceptions include (but aren't limited to) example modules, IANA-maintained YANG modules, and modules in AD-sponsored documents. For other standards organizations, a similar approach is also suggested.
The "contact" statement MUST be present ๐. For Standards Track documents, the WG web and mailing information SHOULD be present, and the main document author or editor contact information SHOULD be present too. If there are additional authors or editors, their contact information MAY be present. You do NOT need to include the contact info 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, and it MUST contain the following statement โ๏ธ:
| All revisions of IETF and IANA published modules can be found at
| the "YANG Parameters" registry group:
| <https://www.iana.org/assignments/yang-parameters>.If the module relies on information in other documents, which are NOT the same documents implied by the "import" statements in the module, then those 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, and it MUST identify the published document that contains the module. Modules get pulled out of their original documents all the time, so it helps developers and operators find the original source in a consistent way ๐ต๏ธโโ๏ธ. The "revision" statement MAY have a "description" substatement. For convenience, the description of a new published revision can summarize any changes made compared to the previous published revision. Usually that list is a YANG-specific subset of the summary of changes from the RFC being updated or obsoleted, as per [ID-Guidelines] ๐.
Here's the "revision" statement for a published YANG module:
revision 2010-09-24 {
description
"Initial revision.";
reference
"RFC 6021: Common YANG Data Types";
}And here's a published YANG module that updates a published module. The new "revision" statement summarizes the changes compared to the previous published revision ๐:
revision 2013-07-15 {
description
"This revision adds the following new data types:
- yang:yang-identifier
- yang:hex-string
- yang:uuid
- yang:dotted-quad";
reference
"RFC 6991: Common YANG Data Types";
}
revision 2010-09-24 {
description
"Initial revision.";
reference
"RFC 6021: Common YANG Data Types";
}For an unpublished module, you don't need a full history of every unpublished revision ๐ฑ. Within a sequence of draft versions, only the most recent revision needs to be recorded in the module. Do not remove or reuse a "revision" statement for a published module โ. A new revision date isn't required unless the module contents have changed. If they HAVE changed, then the revision date of that new version MUST be updated to a date later than the previous version's date ๐.
Last one, the unpublished update to a published YANG module ๐ฅ. The latest "revision" statement summarizes the changes compared to the previous revision:
revision 2025-12-22 {
description
"This revision adds the following new data types:
- yang:date
- yang:date-no-zone
- yang:time
- yang:time-no-zone
- yang:hours32
- yang:minutes32
- yang:seconds32
- yang:centiseconds32
- yang:milliseconds32
- yang:microseconds32
- yang:microseconds64
- yang:nanoseconds32
- yang:nanoseconds64
- yang:language-tag
The yang-identifier definition has been aligned with YANG
1.1 and types representing time support the representation
of leap seconds. The representation of time zone offsets
has been aligned with RFC 9557. Several description and
pattern statements have been improved.";
reference
"RFC 9911: Common YANG Data Types";
}
revision 2013-07-15 {
description
"This revision adds the following new data types:
- yang:yang-identifier
- yang:hex-string
- yang:uuid
- yang:dotted-quad";
reference
"RFC 6991: Common YANG Data Types";
}
revision 2010-09-24 {
description
"Initial revision.";
reference
"RFC 6021: Common YANG Data Types";
}4.9. Namespace Assignments ๐
Okay bestie, so it is RECOMMENDED that only valid YANG modules go into documents, even if the modules aren't published yet ๐ This is giving three big wins:
- the module compiles correctly instead of throwing disruptive fatal errors ๐
- early implementors can use the modules without picking a random value for the XML namespace ๐ง
- early interoperability testing actually works, since independent implementations all use the same XML namespace value ๐ซถ
Until the IANA assigns a URI, a proposed namespace URI MUST be provided for the "namespace" statement in a YANG module. You SHOULD pick a value 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 group MUST NOT be used. Do not be that person ๐
A standard "namespace" statement value SHOULD have this form:
<URN prefix string>:<module-name>The following URN prefix string SHOULD be used for published and unpublished YANG modules:
urn:ietf:params:xml:ns:yangThese 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-netconfHeads up: 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 Section 5.3 of [RFC7950]. ๐ฅ
The following URIs show what might be used by modules that are not Standards Track. The domain "example.com" SHOULD be used by example modules in I-Ds from the IETF Stream. These URIs are not intended to be dereferenced. They are only used for module namespace identification, so don't go clicking them ๐ญ
Example URIs using URLs per [RFC3986]:
https://example.com/ns/example-interfaces
https://example.com/ns/example-systemExample URIs using tags per [RFC4151]:
tag:example.com,2017:example-interfaces
tag:example.com,2017:example-system4.10. Top-Level Data Definitions ๐
The top-level data organization SHOULD be thought through carefully, in advance. Data model designers need to think about how the functionality for a protocol (or protocol family) will grow over time ๐ฆ
The separation of configuration data and operational state SHOULD also be considered carefully. Sometimes it's useful to define separate top-level containers for configuration and non-configuration data. For some existing top-level data nodes, configuration data wasn't in scope, so only one container representing operational state was created. Refer to NMDA [RFC8342] for details ๐
The number of top-level data nodes in a module SHOULD be minimized. It's often useful to retrieve related information within a single subtree, and if data is too spread out, it gets hard to grab everything at once ๐
Names and data organization SHOULD reflect persistent information, like the name of a protocol. The name of the working group SHOULD NOT be used, because that may change over time ๐
A mandatory database data definition is 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 shows up at the top level, it will immediately make the database invalid. This can happen when the server boots, or when a module is loaded dynamically at runtime. Yikes ๐ญ
4.11. Data Types ๐
Picking the right data type (built-in type, existing derived type, or new derived type) is very subjective, so few requirements can be specified on that subject. It's giving vibes more than rules ๐ฆ
Data model designers SHOULD use the most appropriate built-in data type for the particular application ๐
The signed numeric data types ("int8", "int16", "int32", and "int64") SHOULD NOT be used unless negative values are allowed for the desired semantics. Don't add negatives you don't need ๐
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 (e.g., IANA), then an "enumeration" data type SHOULD be used ๐
leaf foo {
type enumeration {
enum one;
enum two;
}
}If distributed extensibility or hierarchical organization of enumerated values is required, then the "identityref" data type SHOULD be used instead of an "enumeration" or other built-in type. It's the extensible queen ๐
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;
}
}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. Main character energy ๐ธ
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 [RFC9911] shows the proper use of the "pattern" statement:
typedef ipv6-address-no-zone {
type inet:ipv6-address {
pattern '[0-9a-fA-F:\.]*';
}
...
}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. Non-negotiable ๐ฅ
The following typedef from [RFC9911] shows 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 from those allowed by the unbounded intrinsic data type (e.g., "int32"), then a range statement SHOULD be present โจ
The following typedef from [RFC9911] shows 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";
}
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. Order matters, bestie ๐
In the following example, the "enumeration" type will never be matched, because the preceding "string" type matches everything. Oops ๐
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 ๐ฆ
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 matches 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 isn't 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) doesn't take up any bytes in a representation. The disadvantage is that the client may not be sure whether an empty leaf is missing because it was filtered out or not implemented. The client may not have a complete and accurate schema for the data returned by the server, so it may not even notice 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 the client explicitly requests it, so no bytes are used in a typical representation โจ
In general, the "boolean" data type SHOULD be used instead of the "empty" data type, as shown in this example:
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 [RFC9911], then it SHOULD be used instead of defining a new derived type. Don't reinvent the wheel, babe ๐
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. That way they're easy to reuse without unnecessary coupling ๐ง
The "description" statement MUST be present. No exceptions, no cap ๐
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 โจ
okay bestie, so a reusable grouping is a YANG grouping that another module can import and use ๐. It's not the same as a grouping that only gets used inside the module it lives in. It just happens to be exportable because it's defined at the top level of the YANG module ๐.
To make these as robust as possible, here are the guidelines ๐ซถ:
- Clearly identify the purpose of the grouping in the
descriptionstatement ๐. Tell people why it exists! - 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. Five contexts, periodt ๐ . - Do not reference data outside the grouping in any
path,must, orwhenstatements ๐ . - Do not include a
defaultsubstatement on a leaf or choice unless the value applies on all possible contexts ๐ธ. - Do not include a
configsubstatement on a data node unless the value applies on all possible contexts ๐. - Clearly identify any external dependencies in the grouping
descriptionstatement, such as nodes referenced by an absolute path from apath,must, orwhenstatement ๐ฅ.
4.14. Data Definitions
The description statement MUST be present in the following YANG statements ๐:
- anydata
- anyxml
- augment
- choice
- container
- extension
- feature
- grouping
- identity
- leaf
- leaf-list
- list
- notification
- rpc
- 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 <b> and </b>, 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. Use the other types when you can, bestie ๐.
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 be supported. Ugh, the struggle is real.
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. Nested choices are giving confusing, bestie.
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.
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 { ... }
}Using non-presence containers to organize data is a subjective matter, kind of like using 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). Parent containers to the rescue ๐ซถ.
4.14.2. Top-Level Data Nodes
Use of top-level objects needs to be considered carefully ๐ง:
- top-level siblings are not ordered
- top-level siblings are not static and depend on the modules that are loaded
- for subtree filtering, retrieval of a top-level leaf-list will be treated as a content-match node for all top-level-siblings
- 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 ๐จ. Harmful operations are NOT a vibe, so flag them loud and proud.
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. Spill the tea in the description, okay? ๐ต
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. Don't be that person ๐ โโ๏ธ.
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 identify. Module names with a common prefix can help readers identify 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. Republishing is such a hassle, bestie ๐ฉ.
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";
}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, so pay attention!
The when statement causes data node instances to be silently deleted as soon as the condition becomes false ๐ป. A false when statement is not considered to be an error. Poof, gone, no drama ๐จ.
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). Two nodes, one rule, big vibes โฐ.
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 ๐.
The following example from [RFC8343] 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 โจ
okay bestie, YANG has very specific rules for how config data can get updated in new releases of a module ๐ and those rules are what let an "old client" keep vibing with a "new server" ๐ซถ
If data nodes get added to an existing entry, the old client MUST NOT be required to provide any mandatory parameters that weren't in the original module definition ๐ โโ๏ธ
It's possible to add conditional augment statements where the old client wouldn't even know the new condition exists, so it would never specify it ๐ A conditional augment statement can only contain mandatory objects if the condition is false, unless the client explicitly requests otherwise.
Only a conditional augment statement that uses the when statement form of a condition can work this way ๐ The client has zero control over which YANG features the server enables, so it's 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 has no control over that external data ๐
In the following sample, it's okay to augment the interface entry with mandatory-leaf because the augmentation depends on support for some-new-iftype ๐ฆ The old client doesn't know about this type, so it would never select it, and therefore it wouldn't add a mandatory data node โจ
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 only safe for creating data resources ๐ It's not safe for replacing or modifying resources if the client doesn't 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's 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 isn't required to know about my-module just because it knows about the iana-if-type module ๐
4.20. Deviation Statements ๐
Per Section 7.20.3 of [RFC7950], the YANG deviation statement is not allowed to appear in IETF YANG modules, but it can be super useful for documenting server capabilities ๐ Deviation statements aren't reusable and typically aren't shared across all platforms.
There are several reasons deviations might be needed in an implementation, e.g., an object can't be supported on all platforms, or feature delivery happens in multiple development phases ๐ Deviation statements can also be used to add annotations to a module, which doesn't affect the conformance requirements for the module ๐
It's suggested that deviation statements be defined in separate modules from regular YANG definitions ๐๏ธ This lets the deviations be platform specific and/or temporary.
The order that deviation statements get evaluated in can change the result ๐ต So multiple deviation statements in the same module, for the same target object, SHOULD NOT be used.
The max-elements statement is meant to describe an architectural limit on the number of list entries. It is not meant to describe platform limitations ๐
โโ๏ธ It's better to use a deviation statement for 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. It shows up in the YANG syntax as an unknown-statement ๐งฉ Using extension statements in a published module needs to be considered carefully, bestie ๐ซถ
The following guidelines apply to the usage of YANG extensions:
- The semantics of the extension MUST NOT contradict any YANG statements. Extensions can add semantics that the normal YANG statements don't cover โจ
- The module containing the
extensionstatement 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 implement the extension too. If not, identify what conditions apply that would require implementing the extension ๐ - The extension MUST clearly identify where it can be used within other YANG statements ๐
- 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 a bunch of ways, using common data types, common data naming, and common data organization ๐ There are several ways to extend the functionality of a module, depending on how tightly coupled the old and new functionality is:
- 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.
- 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.
- mirror: create new objects in a new module or the original module, except with a new naming scheme and data location. The naming can be coupled in different ways. Tight coupling is achieved with a
leafrefdata type, with therequire-instancesubstatement set totrue. This method SHOULD be used ๐
If the new data instances aren't 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] ๐ธ
4.22.1. Use of "leafref" for Key Correlation
Sometimes it's not practical to augment a data structure ๐ For example, the correlated data could have different keys or contain mandatory nodes.
Here's how the leafref data type gets used 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 {
type string;
mandatory true;
}
}4.23. Operational State ๐ง
The modeling of operational state with YANG has been glowing up over time โจ At first, only data with a config statement value of false counted as operational state. That data wasn't considered part of any datastore, which made the YANG XPath definition way more complicated ๐ฉ
Operational state is now modeled using YANG according to NMDA [RFC8342], and it's conceptually contained in the operational state datastore, which also includes the operational values of configuration data ๐ There's no longer any need to duplicate data structures just to provide separate configuration and operational state sections.
This section covers some data modeling issues related to operational state, plus 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 when retrieving dynamic entries, and it lets configuration and operational state 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 from the operational value set for that object, like 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.
Sometimes the list keys aren't 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's 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 don't exist in the associated configuration data ๐ฆ
The need to replicate objects or define different operational state objects depends on the data model ๐คทโโ๏ธ It's 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 ๐ฆ
Okay bestie, so YANG modules SHOULD be designed assuming they'll be running on servers that support the operational state datastore ๐ง. With that in mind, modules SHOULD define config false nodes wherever they make sense for the data model โจ. A config false node SHOULD NOT be defined just to give the operational value of a configuration node ๐, EXCEPT when the value space of a configured value and its operational value may differ. In that case, a separate config false node SHOULD be defined to hold the operational value for the configured node ๐
.
These guidelines are here to help modelers build YANG modules that get the most out of both current and new implementations ๐ธ.
New modules, and modules that don't care about 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 doesn't contain any configuration datastore objects ๐ซถ.
The rest are options that MAY be followed while NMDA mechanisms are still being defined ๐.
(a) Modules that need immediate support for the NMDA features SHOULD be structured for NMDA ๐ฅ. A temporary non-NMDA version of this type of module MAY exist, either as an existing module or as a module 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 the NMDA modules in the document main body and the non-NMDA modules in a non-normative appendix ๐. The non-NMDA module will let things bridge the gap until NMDA implementations are available ๐ท.
(b) For published modules, the module should be republished with an NMDA-compatible structure, deprecating non-NMDA constructs ๐. For example, the ietf-interfaces module in [RFC7223] was restructured as an NMDA-compatible module in [RFC8343] (which obsoletes [RFC7223]) ๐ฆ. The /interfaces-state hierarchy was marked with status deprecated ๐
. Modules that mark their /foo-state hierarchy with status deprecated let NMDA-capable implementations skip the cost of duplicating the state nodes, while non-NMDA-capable implementations can still use them to get at the operational values โจ.
(c) For modules that augment modules that haven't been structured with NMDA, the modeler has to think about the structure of the base module and the guidelines above ๐ง. Where possible, such modules should move to new revisions of the base module that are NMDA compatible. When that isn't possible, augmenting state containers SHOULD be avoided, with the expectation that the base module will be re-released with the state containers marked as deprecated ๐. It is RECOMMENDED to augment only the /foo hierarchy of the base module ๐ฏ. If this recommendation can't be followed, any new state elements SHOULD be included in their own module ๐ซถ.
4.23.3.1. Temporary Non-NMDA Modules ๐ง
A temporary non-NMDA module lets a non-NMDA-aware client 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 (from 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 that the foo-state subtree lives in a different (temporary) module ๐ธ. The NMDA module can be used by a non-NMDA client to reach the conventional configuration datastores and the deprecated <get> operation, which gets nested config false data nodes โจ.
To create the temporary non-NMDA module from an NMDA module, you can take the following steps ๐ ๏ธ:
- Change the module name by appending
-stateto the original module name. - Change the namespace by appending
-stateto the original namespace value. - Change the prefix by appending
-sto the original prefix value. - Add an import to the original module (e.g., for typedef definitions).
- Retain or create only the top-level nodes that have a
configstatement value offalse. These subtrees representconfig falsedata nodes that were combined into the configuration subtree, so they aren't available to non-NMDA-aware clients ๐ฅบ. Set thestatusstatement todeprecatedfor each new node ๐. - 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: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
}
}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: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: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
}
}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: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's generally true that certain YANG statements need more runtime resources than others ๐ญ. There are no performance requirements for YANG validation, but the following information MAY be considered when designing YANG data models โจ:
- Lists are generally more expensive than containers.
whenstatement evaluation is generally more expensive thanif-featureorchoicestatements.muststatements are generally more expensive thanmin-elements,max-elements,mandatory, oruniquestatements.identityrefleafs are generally more expensive thanenumerationleafs.leafrefandinstance-identifiertypes withrequire-instanceset totrueare generally more expensive than whenrequire-instanceis set tofalse๐ซ .
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 ๐ฆ.
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 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 way more expressive than YANG 1.0 ๐คฏ. A description statement SHOULD describe the if-feature logic in text, so readers can understand the module ๐.
YANG features SHOULD be used instead of the when statement, if possible ๐. Features are advertised by the server, and objects conditional on the if-feature statement are conceptually grouped together. There's no such commonality supported for when statements ๐.
Features generally need less server implementation complexity and fewer 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 โก
Using action statements or rpc statements is a subjective design decision ๐คทโโ๏ธ. RPC operations aren't 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 ๐ฏ.
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 one 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] doesn't 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 can't be used ๐.
For example, NACM can't 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 doesn't have read access to the specific interface instance, then they can't invoke the reset action for that interface instance ๐:
container interfaces {
list interface {
...
action reset { }
}
}4.27. Updating YANG Modules (Published versus Unpublished) ๐โจ
YANG modules change over time, bestie ๐ฆ Usually they get new data model definitions because new features need them. The YANG update rules defined in Section 11 of [RFC7950] MUST be followed for published modules. For unpublished modules, they MAY be followed ๐
The YANG update rules only apply to published module revisions ๐ Every organization has its own way of marking published work as stable and unpublished work as unstable. In the IETF, for example, an RFC is the published stuff and an I-D is the unpublished stuff ๐ธ
4.28. Defining Standard Tags ๐ท๏ธ
[RFC8819] is the spec that lets you attach tags to YANG modules ๐ Tags can be defined and associated at design time, at implementation time, or through user administrative control. Design-time tags use the module-tag "extension" statement ๐ง
A module MAY use module-tag "extension" statements to indicate a set of tags that get associated with it automatically (so, not added through configuration) ๐
module example-module {
namespace "https://example.com/yang/example";
prefix "ex";
//...
import module-tags { prefix tags; }
tags:module-tag "ietf:some-new-tag";
tags:module-tag "ietf:some-other-tag";
// ...
}Authors can use existing standard tags or make new ones defined in the model definition, whichever fits best ๐ซถ For IETF modules, new tags MUST be assigned in the IANA "IETF YANG Module Tags" registry within the "YANG Module Tags" registry group [IANA-TAGS]. Non-negotiable, bestie ๐ญ
4.29. Modeling Abstract Data Structures ๐งฉ
For contexts where YANG is used to model abstract data structures (like protocol messages), using the "structure" extension statement [RFC8791] is RECOMMENDED over the "yang-data" extension statement [RFC8040] ๐ Examples of modules that rely on the "structure" extension statement from [RFC8791] are in [RFC9132] or [RFC9195] ๐
Abstract data structures can be augmented with the "augment-structure" statement [RFC8791] ๐ Examples of modules that augment abstract data structures are in [RFC9244] and [RFC9362] โจ
4.30. IANA-Maintained YANG Modules ๐ธ
4.30.1. Context ๐๏ธ
IANA maintains a set of registries that are key for interoperability ๐ The content is usually available in various formats (like plain text or XML). But people got confused in the past about whether the content of some registries depends on a specific representation format ๐ For example, Section 5 of [RFC8892] was published to clarify that MIB and YANG modules are just additional formats in which the "Interface Types (ifType)" and "Tunnel Types (tunnelType)" registries are available. The MIB [RFC2863] and YANG modules ([RFC7224] [RFC8675]) are not separate registries, and the same values are always present in every format of the same registry ๐
A design where a YANG module puts parameters and values directly in a module that IANA doesn't maintain, while those same values get populated in an IANA registry, can lead to ambiguity and stale info ๐ฌ That design creates another source of information that can drift from the IANA registry as new values get assigned or some values get deprecated.
For consistency, and so new values can still be supported while IANA registries stay the single authoritative source of information, this document recommends using IANA-maintained YANG modules as the single source of information ๐
The next section gives guidelines for YANG module authors on designing IANA-maintained YANG modules ๐ They're meant to leverage existing IANA registries and use YANG as another format to present the content of those registries when appropriate.
4.30.2. Guidelines for IANA-Maintained YANG Modules ๐
When designing a YANG module for functionality governed by a protocol for which IANA maintains a registry, it is RECOMMENDED to specify an IANA-maintained YANG module that echoes the content of that registry. This is superior to putting that content in an IETF-maintained module ๐
When one or multiple registries are available under the same registry group, it is RECOMMENDED to define an IANA-maintained YANG module for each registry. However, module designers MAY consider defining one single IANA-maintained YANG module that covers all registries if maintaining that single module is manageable (for example, very few values are present or expected for each registry). An example of such a module is documented in Section 5.2 of [RFC9132] ๐ง
An IANA-maintained YANG module may use the "identityref" data type approach (for example, [RFC8675]) or an "enumeration" data type approach (for example, [RFC9108]). See Section 4.11.1 for guidance on which data type to use ๐ The decision should be based on specifics related to the intended use of the IANA-maintained YANG module. For example, identities are useful if the registry entries are organized hierarchically, possibly including multiple inheritances. The reasoning for the design choice MUST be documented in the companion specification that registers an IANA-maintained YANG module. For example, [RFC9244] defines an IANA-maintained YANG module that uses enumerations for the following reason ๐ซถ
| The DOTS telemetry module (Section 11.1) uses "enumerations"
| rather than "identities" to define units, samples, and intervals
| because otherwise the namespace identifier "ietf-dots-telemetry"
| must be included when a telemetry attribute is included (e.g., in
| a mitigation efficacy update). The use of "identities" is thus
| suboptimal from the standpoint of message compactness, as message
| compactness is one of the key requirements for DOTS signal channel
| messages.Designers of IANA-maintained YANG modules MAY supply the initial full version of the module in a specification document that registers the module, or only a script to be used (including by IANA) for generating the module. Examples are an Extensible Stylesheet Language Transformations (XSLT) stylesheet as in Appendix A of [RFC9108] or a Python script as in [RFC9645] โจ In both cases, the document that defines an IANA-maintained YANG module MUST include a note saying that the document only documents the initial version of the module and that the authoritative version is to be retrieved from the IANA registry. Also, the IANA-maintained module MUST include the following note naming the RFC that registered the initial version of the IANA-maintained YANG module:
| The initial version of this YANG module is part of RFC IIII; see
| the RFC itself for full legal notices.It is RECOMMENDED to include the URL where the recent version of the module can be retrieved ๐ When a script is used, the Internet-Draft that defines an IANA-maintained YANG module has to include an appendix with the full script, and SHOULD include an appendix with the initial full version of the module. Including that appendix in Internet-Drafts is meant to assess whether the script's outcome is correct ๐งช The authors MUST include a note to the RFC Editor requesting that the appendix with the initial version of the module be removed before publication as an RFC, and that RFC IIII be replaced with the RFC number assigned to the document ๐ฎ Initial versions of IANA-maintained YANG modules published in RFCs may be misused, despite the language pointing to the IANA registry for the up-to-date module. That's a problem for interoperability, for example when values are deprecated or get a new meaning ๐ญ
| Note: [Style] provides XSLT 1.0 stylesheets and other tools for | translating IANA registries to YANG modules. The tools can be | used to generate up-to-date revisions of an IANA-maintained | YANG module based upon the XML representation of an IANA | registry.If an IANA-maintained YANG module is imported by another module, a normative reference with the IANA URL to retrieve the IANA-maintained YANG module SHOULD be included ๐ Referencing the RFC that defines the initial version of the IANA module is acceptable in specific cases (for example, the imported version is specifically the initial version, or the RFC has useful description about using the module), though not encouraged ๐
Examples of IANA URLs to retrieve the latest version of an IANA-maintained YANG module:
https://www.iana.org/assignments/iana-bgp-l2-encapshttps://www.iana.org/assignments/iana-pseudowire-typeshttps://www.iana.org/assignments/iana-bfd-types
IANA_FOO_URL is used below to refer to such URLs. These URLs are expected to be sufficiently permanent and stable ๐
Whenever you need to reference a specific version of an IANA-maintained YANG module, URLs like this one are used:
IANA_FOO_URL_With_REV is used below to refer to such URLs ๐
A template for IANA-maintained YANG modules is provided in Appendix C ๐ง
4.30.3. Guidance for Writing the IANA Considerations for RFCs Defining IANA-Maintained YANG Modules โจ
okay so bestie, in addition to the IANA considerations from Section 3.8, the IANA Considerations section of an RFC with an IANA-maintained YANG module MUST include the instructions IANA needs to keep that module up to date automatically ๐ค๐ . These instructions explain how to handle updates triggered by a change to the authoritative registry. Concretely, the IANA Considerations section SHALL at least cover the following:
- ask IANA to add a note to the page about the IANA-maintained YANG module saying that new values must not be directly added to the module ๐ โโ๏ธ. Those values should go into an authoritative IANA registry instead.
- ask IANA to add a note to the authoritative IANA registry saying that any change to the registry must be reflected in the matching IANA-maintained YANG module. So basically, every registry change has to come with an update to that module ๐.
- spell out the actions needed to update the module to match the registry, like adding a new "identity" or "enum" statement ๐งฉ. Usually this means describing how to make a new "identity" statement name with its substatements ("base", "status", "description", and "reference"), or a new "enum" statement with its substatements ("value", "status", "description", and "reference").
- when you create a new "identity" statement name or a new "enum" statement, it is RECOMMENDED to use the same name (if there is one) that's recorded in the IANA registry ๐.
- if the name in the IANA registry doesn't follow the naming conventions in Section 4.3.1, the procedure MUST explain how IANA can generate legal identifiers from that name ๐ช. Specifically, if the name starts with a number, it is RECOMMENDED to spell out the number when it's used as an identifier (so, not use a digit). IANA should be given instructions to do this. For example, authors of a module with identifiers like this have to say whether:
- if a new registration uses an identifier that doesn't follow the naming conventions in Section 4.3.1, IANA should first check whether the RFC that specified the module's first version gave guidance on making legal identifiers ๐ต๏ธโโ๏ธ. If there's no such guidance, IANA should check the latest revision of the IANA-maintained YANG module for similar patterns. And if all else fails, IANA should ask the relevant registry experts (like the designated experts for a registry using the Expert Review policy (Section 4.5 of [RFC8126]), or the responsible area director) ๐โโ๏ธ.
The IANA Considerations Section MAY also include the following if a default action is going to be overridden ๐:
- a note on whether unassigned or reserved values should be present in the IANA-maintained YANG module. If no instruction is given, unassigned or reserved values must not be present in the module ๐ซ.
- an instruction on whether experimental values should be included in the module. If no instruction is given, experimental values MUST NOT be listed in the IANA-maintained YANG module ๐งช.
- an instruction on how to generate the "revision" statement. If no instruction is given, the default actions in Section 5.3 will be followed ๐ .
A template for the IANA Considerations is provided in Section 4.30.3.1 for IANA-maintained YANG modules with identities, and in Section 4.30.3.2 for IANA-maintained YANG modules with enumerations ๐ฆ. Authors may tweak the template to fit their module. For example, multiple registries can be listed for a single IANA-maintained YANG module, there might be no explicit description (or name) field under the authoritative IANA registry, or the name might not follow YANG naming conventions (Section 4.3.1) ๐.
Here's an example of "revision" statements generated by following the guidance in Section 5.3.2 ๐ธ:
revision 2023-11-27 {
description
"Registered RR Type RESINFO 261.";
reference
"https://www.iana.org/assignments/yang-parameters/"
+ "iana-dns-class-rr-type@2023-11-27.yang";
}
revision 2023-11-08 {
description
"Updated description and replaced draft string reference to
64 and 65 with RFC 9460: Service Binding and Parameter
Specification via the DNS (SVCB and HTTPS Resource Records).";
reference
"RFC 9460: Service Binding and Parameter Specification via the
DNS (SVCB and HTTPS Resource Records)
https://www.iana.org/assignments/yang-parameters/"
+ "iana-dns-class-rr-type@2023-11-08.yang";
}
revision 2023-04-25 {
description
"Updated reference for 64 and 65.";
reference
"https://www.iana.org/assignments/yang-parameters/"
+ "iana-dns-class-rr-type@2023-04-25.yang";
}
revision 2022-05-30 {
description
"Updated description, reference for 64 and 65.";
reference
"https://www.iana.org/assignments/yang-parameters/"
+ "iana-dns-class-rr-type@2022-05-30.yang";
}
revision 2021-08-31 {
description
"Initial revision.";
reference
"RFC 9108: YANG Types for DNS Classes and Resource Record
Types";
}Repeating the same reference at the top level and at the level of a new addition can be redundant ๐. For example, the following doesn't give access to a specific (OLD) revision of the module once future revisions come out [IANA_Tunnel_Type_URL]:
revision 2021-04-23 {
description
"Registered tunnelType 19.";
reference
"RFC 4301: Security Architecture for the Internet Protocol";
}
revision 2019-11-16 {
description
"Initial revision.";
reference
"RFC 8675: A YANG Data Model for Tunnel Interface Types";
}
...
identity ipsectunnelmode {
base ift:tunnel;
description
"IpSec tunnel mode encapsulation.";
reference
"RFC 4301: Security Architecture for the Internet Protocol";
}Here's how to generate the "revision" statements following the guidance in Section 5.3.2 โจ:
revision 2021-04-23 {
description
"Registered tunnelType 19.";
reference
"https://www.iana.org/assignments/yang-parameters/"
+ "iana-tunnel-type@2021-04-23.yang
RFC 4301: Security Architecture for the Internet Protocol";
}
revision 2019-11-16 {
description
"Initial revision.";
reference
"RFC 8675: A YANG Data Model for Tunnel Interface Types";
}
...
identity ipsectunnelmode {
base ift:tunnel;
description
"IpSec tunnel mode encapsulation.";
reference
"RFC 4301: Security Architecture for the Internet Protocol";
}The templates in the following subsections should be considered in addition to the required information in Section 3.8 ๐ง.
4.30.3.1. Template for IANA-Maintained YANG Modules with Identities ๐
Here's the template text for identities ๐:
<BEGIN TEMPLATE TEXT>
This document defines the initial version of the IANA-maintained
"iana-foo" YANG module. The most recent version of the YANG module
is available from the "YANG Parameters" registry group
[IANA-YANG-PARAMETERS].
IANA is requested to add this note to the registry:
New values must not be directly added to the "iana-foo" YANG
module. They must instead be added to the "foo" registry.
IANA is requested to add this note to [reference-to-the-iana-foo-
registry]:
When this registry is modified, the YANG module "iana-foo"
[IANA_FOO_URL] must be updated as defined in RFC IIII.
When a value is added to the "foo" registry, a new "identity"
statement needs to be added to the "iana-foo" YANG module.
The name of the "identity" MUST be the name as provided in the
registry. The "identity" statement should have the following
substatements defined:
"base": Contains 'name-base-identity-defined-in-foo'.
"status": Include only if a registration has been deprecated or
obsoleted. IANA "deprecated" maps to YANG status
"deprecated", and IANA "obsolete" maps to YANG status
"obsolete".
"description": Replicates the description from the registry.
"reference": Replicates the reference(s) from the registry with
the title of the document(s) added.
-- Optional:
-- Include only text that needs to be customized for the module.
-- Text that does not require customization should be
-- omitted.
-- Notes tagged with "--" include instructions for authors. These
-- notes must not be copied.
Unassigned and Reserved Values:
-- To be completed only if unassigned and/or reserved values
-- (which may include experimental values) should be included
-- in the module. These values are typically not included.
Description Substatements:
-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements,
-- "identity" statements, or both.
Reference Substatements:
-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements,
-- "identity" statements, or both.
Naming Considerations:
-- If a name in the IANA registry does not comply with the
-- YANG naming conventions, add details how IANA can generate
-- legal identifiers. For example, if the name begins with
-- a number, indicate a preference to spell out the number when
-- used as an identifier.
<END TEMPLATE TEXT>4.30.3.2. Template for IANA-Maintained YANG Modules with Enumerations โจ
okay bestie, this is the template for when the IANA-maintained module is built from an enumeration (aka an enum list) instead of identities ๐ฆ here's the copy-paste-ready text, the -- notes are for authors only and never get copied ๐
<BEGIN TEMPLATE TEXT>
This document defines the initial version of the IANA-maintained
"iana-foo" YANG module. The most recent version of the YANG module
is available from the "YANG Parameters" registry group
[IANA-YANG-PARAMETERS].
IANA is requested to add this note to the registry:
New values must not be directly added to the "iana-foo" YANG
module. They must instead be added to the "foo" registry.
When a value is added to the "foo" registry, a new "enum" statement
must be added to the "iana-foo" YANG module. The "enum" statement,
and substatements thereof, should be defined:
"enum": Replicates a name from the registry.
"value": Contains the decimal value of the IANA-assigned
value.
"status": Is included only if a registration has been
deprecated or obsoleted. IANA "deprecated" maps
to YANG status "deprecated", and IANA "obsolete"
maps to YANG status "obsolete".
"description": Replicates the description from the registry.
"reference": Replicates the reference(s) from the registry.
References to documents should also include titles.
-- Optional:
-- Include only text that needs to be customized for the module.
-- Text that does not require customization should be
-- omitted.
-- Notes tagged with "--" include instructions for authors. These
-- notes must not be copied.
Unassigned and Reserved Values:
-- To be completed only if unassigned and/or reserved values
-- (which may include experimental values) should be included
-- in the module. These values are typically not included.
Description Substatements:
-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements, "enum"
-- statements, or both.
Reference Substatements:
-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements, "enum"
-- statements, or both.
Naming Considerations:
-- If a name in the IANA registry does not comply with the
-- YANG naming conventions, add details how IANA can generate
-- legal identifiers. For example, if the name begins with
-- a number, indicate a preference to spell out the number when
-- used as an identifier.
<END TEMPLATE TEXT>5. IANA Considerations โจ
5.1. YANG Modules
okay so this part is IANA's paperwork ๐ the ns registration was first detailed in [RFC8407], and IANA has since updated it to point at this document ๐ the new namespace and module entries look like this:
URI: urn:ietf:params:xml:ns:yang:ietf-template
Registrant Contact: The IESG
XML: N/A; the requested URI is an XML namespace.IANA has also registered the following URI in the "ns" registry within the "IETF XML Registry" registry group [RFC3688]:
URI: urn:ietf:params:xml:ns:yang:iana-template
Registrant Contact: The IESG
XML: N/A; the requested URI is an XML namespace.And the YANG modules got their spots in the "YANG Module Names" registry [RFC6020] [RFC9890] inside the "YANG Parameters" registry group ๐ธ
Name: ietf-template
Maintained by IANA? N
Namespace: urn:ietf:params:xml:ns:yang:ietf-template
Prefix: temp
Reference: RFC 9907
Name: iana-template
Maintained by IANA? N
Namespace: urn:ietf:params:xml:ns:yang:iana-template
Prefix: iana-foo
Reference: RFC 99075.2. Update in YANG Parameters Registry Group
the "YANG Module Names" registry under the "YANG Parameters" registry group also got a glow-up ๐ง IANA updated [RFC8407] to point at this document, since it holds the template you need for registration in Appendix B. main character energy ๐
5.3. IANA-Maintained YANG Modules
IANA should refer to Section 4.30.3 for the info needed to fill in "revision" statements and the "identity" and "enum" substatements in IANA-maintained YANG modules ๐
These considerations cover both making and maintaining an IANA-maintained YANG module. They include instructions that apply to every IANA-maintained module, plus instructions that module creators are allowed to customize ๐ซถ
5.3.1. Requirements for All Modules
here are the instructions that should apply to all modules, no exceptions ๐ฅ
- When a YANG module is updated, a new
revisionstatement with a unique revision date must be added in front of the existing revision statements. Therevisionstatement MUST contain bothdescriptionandreferencesubstatements, as described in Section 5.3.2. - When an underlying registration is deprecated or obsoleted, a corresponding
statussubstatement should be added to theidentityorenumstatement. - The
referencesubstatement in therevisionstatement should point specifically to the published module (i.e.,IANA_FOO_URL_With_REV). When the registration is triggered by an RFC, that RFC must also be included in thereferencesubstatement. It may also point to an authoritative event that triggered the update to the YANG module. In all cases, the event is cited from the underlying IANA registry. - References to documents should include titles.
and when the module gets published, IANA must add these notes too ๐
the YANG Module Names registry gets this one:
New values must not be directly added to the "iana-foo" YANG
module. They must instead be added to the "foo" registry.the underlying registry gets this one:
When this registry is modified, the YANG module "iana-foo"
[IANA_FOO_URL] must be updated as defined in RFC IIII.5.3.2. Requirements Subject to Customization
unless the creators of an IANA-maintained YANG module say otherwise in their document's IANA Considerations section, these defaults apply ๐
- Unassigned and reserved values (including experimental values) will be omitted from the module.
- The
referencesubstatement in anidentityorenumstatement should mirror the underlying registry. It may point to contact names as well as documents. - In a
revisionstatement, thedescriptionsubstatement captures what changed in the revised version. Usually thedescriptionlists things like updates to existing entries (e.g., updating adescriptionor areference), or it notes which identities were added or had their status changed (e.g., deprecated, discouraged, or obsoleted).
When a description like that isn't feasible, the description depends on what triggered the update.
If the update is triggered by an RFC, the description substatement should include or consist of this text:
Applied updates as specified by RFC XXXX.If the registration policy for the registry does not require RFC publication (Section 4 of [RFC8126]), insert this text:
Applied updates as specified by the registration policy
<Some_IANA_policy>.6. Operational Considerations ๐ธ
okay so this doc is all about YANG data modeling guidance, and it does NOT define a protocol or a protocol extension ๐ง which means there are no new operations or manageability requirements coming from it. zero new vibes to manage, bestie ๐
7. Security Considerations ๐ฅ
this is the serious bit, so we're keeping it real ๐ this document defines guidelines for NETCONF or RESTCONF content written in the YANG data modeling language. It does not introduce any new or increased security risks. โจ
8. References ๐
8.1. Normative References
every reference, with all its details, lives right here ๐
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[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,
<https://www.rfc-editor.org/info/rfc3986>.
[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,
<https://www.rfc-editor.org/info/rfc5378>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[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,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
RFC 7952, DOI 10.17487/RFC7952, August 2016,
<https://www.rfc-editor.org/info/rfc7952>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[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,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341,
DOI 10.17487/RFC8341, March 2018,
<https://www.rfc-editor.org/info/rfc8341>.
[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,
<https://www.rfc-editor.org/info/rfc8342>.
[RFC8791] Bierman, A., Bjรถrklund, M., and K. Watsen, "YANG Data
Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,
June 2020, <https://www.rfc-editor.org/info/rfc8791>.
[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
"Handling Long Lines in Content of Internet-Drafts and
RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
<https://www.rfc-editor.org/info/rfc8792>.
[RFC8819] Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module
Tags", RFC 8819, DOI 10.17487/RFC8819, January 2021,
<https://www.rfc-editor.org/info/rfc8819>.
[RFC9890] Bierman, A., Boucadair, M., Ed., and Q. Wu, "An Update to
YANG Module Names Registration", RFC 9890,
DOI 10.17487/RFC9890, October 2025,
<https://www.rfc-editor.org/info/rfc9890>.
[W3C.REC-xpath]
Clark, J., Ed. and S. DeRose, Ed., "XML Path Language
(XPath) Version 1.0", W3C Recommendation, 16 November
1999, <https://www.w3.org/TR/1999/REC-xpath-19991116>.8.2. Informative References โจ
okay bestie, this is the "for your reading pleasure" pile ๐๐ง Here's every reference, in the original order, with all the details intact.
[Err5693]RFC Errata, Erratum ID 5693, RFC 8407,<https://www.rfc-editor.org/errata/eid5693>.[Err5800]RFC Errata, Erratum ID 5800, RFC 8407,<https://www.rfc-editor.org/errata/eid5800>.[Err6899]RFC Errata, Erratum ID 6899, RFC 8407,<https://www.rfc-editor.org/errata/eid6899>.[Err7416]RFC Errata, Erratum ID 7416, RFC 8407,<https://www.rfc-editor.org/errata/eid7416>.[IANA-MOD-NAMES]IANA, "YANG Module Names",<https://www.iana.org/assignments/yang-parameters/>.[IANA-TAGS]IANA, "YANG Module Tags",<https://www.iana.org/assignments/yang-module-tags/>.[IANA-XML]IANA, "IETF XML Registry",<https://www.iana.org/assignments/xml-registry/>.[IANA-YANG-PARAMETERS]IANA, "YANG Parameters",<https://www.iana.org/assignments/yang-parameters>.[IANA_Tunnel_Type_URL]IANA, "iana-tunnel-type YANG Module",<https://www.iana.org/assignments/iana-tunnel-type>.[ID-Guidelines]IETF, "Content guidelines overview",<https://authors.ietf.org/en/content-guidelines-overview>.[RFC2026]Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,<https://www.rfc-editor.org/info/rfc2026>.[RFC2606]Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS Names", BCP 32, RFC 2606, DOI 10.17487/RFC2606, June 1999,<https://www.rfc-editor.org/info/rfc2606>.[RFC2863]McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, DOI 10.17487/RFC2863, June 2000,<https://www.rfc-editor.org/info/rfc2863>.[RFC3849]Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix Reserved for Documentation", RFC 3849, DOI 10.17487/RFC3849, July 2004,<https://www.rfc-editor.org/info/rfc3849>.[RFC4151]Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 4151, DOI 10.17487/RFC4151, October 2005,<https://www.rfc-editor.org/info/rfc4151>.[RFC4181]Heard, C., Ed., "Guidelines for Authors and Reviewers of MIB Documents", BCP 111, RFC 4181, DOI 10.17487/RFC4181, September 2005,<https://www.rfc-editor.org/info/rfc4181>.[RFC4252]Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, January 2006,<https://www.rfc-editor.org/info/rfc4252>.[RFC4253]Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, January 2006,<https://www.rfc-editor.org/info/rfc4253>.[RFC5398]Huston, G., "Autonomous System (AS) Number Reservation for Documentation Use", RFC 5398, DOI 10.17487/RFC5398, December 2008,<https://www.rfc-editor.org/info/rfc5398>.[RFC5612]Eronen, P. and D. Harrington, "Enterprise Number for Documentation Use", RFC 5612, DOI 10.17487/RFC5612, August 2009,<https://www.rfc-editor.org/info/rfc5612>.[RFC5737]Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks Reserved for Documentation", RFC 5737, DOI 10.17487/RFC5737, January 2010,<https://www.rfc-editor.org/info/rfc5737>.[RFC7223]Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,<https://www.rfc-editor.org/info/rfc7223>.[RFC7224]Bjorklund, M., "IANA Interface Type YANG Module", RFC 7224, DOI 10.17487/RFC7224, May 2014,<https://www.rfc-editor.org/info/rfc7224>.[RFC7407]Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, December 2014,<https://www.rfc-editor.org/info/rfc7407>.[RFC7951]Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016,<https://www.rfc-editor.org/info/rfc7951>.[RFC8199]Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module Classification", RFC 8199, DOI 10.17487/RFC8199, July 2017,<https://www.rfc-editor.org/info/rfc8199>.[RFC8299]Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data Model for L3VPN Service Delivery", RFC 8299, DOI 10.17487/RFC8299, January 2018,<https://www.rfc-editor.org/info/rfc8299>.[RFC8309]Wu, Q., Liu, W., and A. Farrel, "Service Models Explained", RFC 8309, DOI 10.17487/RFC8309, January 2018,<https://www.rfc-editor.org/info/rfc8309>.[RFC8340]Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,<https://www.rfc-editor.org/info/rfc8340>.[RFC8343]Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,<https://www.rfc-editor.org/info/rfc8343>.[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,<https://www.rfc-editor.org/info/rfc8349>.[RFC8407]Bierman, A., "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 8407, DOI 10.17487/RFC8407, October 2018,<https://www.rfc-editor.org/info/rfc8407>.[RFC8446]Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,<https://www.rfc-editor.org/info/rfc8446>.[RFC8466]Wen, B., Fioccola, G., Ed., Xie, C., and L. Jalil, "A YANG Data Model for Layer 2 Virtual Private Network (L2VPN) Service Delivery", RFC 8466, DOI 10.17487/RFC8466, October 2018,<https://www.rfc-editor.org/info/rfc8466>.[RFC8519]Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, "YANG Data Model for Network Access Control Lists (ACLs)", RFC 8519, DOI 10.17487/RFC8519, March 2019,<https://www.rfc-editor.org/info/rfc8519>.[RFC8675]Boucadair, M., Farrer, I., and R. Asati, "A YANG Data Model for Tunnel Interface Types", RFC 8675, DOI 10.17487/RFC8675, November 2019,<https://www.rfc-editor.org/info/rfc8675>.[RFC8892]Thaler, D. and D. Romascanu, "Guidelines and Registration Procedures for Interface Types and Tunnel Types", RFC 8892, DOI 10.17487/RFC8892, August 2020,<https://www.rfc-editor.org/info/rfc8892>.[RFC8969]Wu, Q., Ed., Boucadair, M., Ed., Lopez, D., Xie, C., and L. Geng, "A Framework for Automating Service and Network Management with YANG", RFC 8969, DOI 10.17487/RFC8969, January 2021,<https://www.rfc-editor.org/info/rfc8969>.[RFC9000]Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, May 2021,<https://www.rfc-editor.org/info/rfc9000>.[RFC9108]Lhotka, L. and P. ล paฤek, "YANG Types for DNS Classes and Resource Record Types", RFC 9108, DOI 10.17487/RFC9108, September 2021,<https://www.rfc-editor.org/info/rfc9108>.[RFC9129]Yeung, D., Qu, Y., Zhang, Z., Chen, I., and A. Lindem, "YANG Data Model for the OSPF Protocol", RFC 9129, DOI 10.17487/RFC9129, October 2022,<https://www.rfc-editor.org/info/rfc9129>.[RFC9132]Boucadair, M., Ed., Shallow, J., and T. Reddy.K, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Specification", RFC 9132, DOI 10.17487/RFC9132, September 2021,<https://www.rfc-editor.org/info/rfc9132>.[RFC9182]Barguil, S., Gonzalez de Dios, O., Ed., Boucadair, M., Ed., Munoz, L., and A. Aguado, "A YANG Network Data Model for Layer 3 VPNs", RFC 9182, DOI 10.17487/RFC9182, February 2022,<https://www.rfc-editor.org/info/rfc9182>.[RFC9195]Lengyel, B. and B. Claise, "A File Format for YANG Instance Data", RFC 9195, DOI 10.17487/RFC9195, February 2022,<https://www.rfc-editor.org/info/rfc9195>.[RFC9244]Boucadair, M., Ed., Reddy.K, T., Ed., Doron, E., Chen, M., and J. Shallow, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry", RFC 9244, DOI 10.17487/RFC9244, June 2022,<https://www.rfc-editor.org/info/rfc9244>.[RFC9291]Boucadair, M., Ed., Gonzalez de Dios, O., Ed., Barguil, S., and L. Munoz, "A YANG Network Data Model for Layer 2 VPNs", RFC 9291, DOI 10.17487/RFC9291, September 2022,<https://www.rfc-editor.org/info/rfc9291>.[RFC9362]Boucadair, M. and J. Shallow, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Configuration Attributes for Robust Block Transmission", RFC 9362, DOI 10.17487/RFC9362, February 2023,<https://www.rfc-editor.org/info/rfc9362>.[RFC9637]Huston, G. and N. Buraglio, "Expanding the IPv6 Documentation Space", RFC 9637, DOI 10.17487/RFC9637, August 2024,<https://www.rfc-editor.org/info/rfc9637>.[RFC9645]Watsen, K., "YANG Groupings for TLS Clients and TLS Servers", RFC 9645, DOI 10.17487/RFC9645, October 2024,<https://www.rfc-editor.org/info/rfc9645>.[RFC9911]Schรถnwรคlder, J., Ed., "Common YANG Data Types", RFC 9911, DOI 10.17487/RFC9911, December 2025,<https://www.rfc-editor.org/info/rfc9911>.[Style]"IANA YANG", commit 3a6cb69, December 2021,<https://github.com/llhotka/iana-yang>.
Appendix A. Module Review Checklist ๐
This section is adapted from [RFC4181] ๐ .
Okay, so a YANG module review is where you check the module for technical correctness and for following the IETF documentation rules. Basically, making sure it's both correct and presentable. ๐ง This checklist might help when you review an I-D:
- I-D Boilerplate: Check that the document has the required sections (see <https://authors.ietf.org/required-content>) ๐.
- Abstract: Check that the abstract has no references and no section number, and that it follows the guidelines in <https://www.ietf.org/id-info/guidelines.html> โจ.
- Copyright Notice: Check that the document has the right text about the rights contributors give to the IETF Trust [RFC5378] ๐ฆ. It also needs the full IETF Trust copyright notice at the very beginning. The IETF Trust Legal Provisions (TLP) live at <https://trustee.ietf.org/license-info/> ๐ธ.
- Security Considerations section: If none of the modules in the document fall under the exceptions in Section 3.7 (for example, using a YANG data structure), check that this section is modeled on the latest approved template from the Operations and Management (OPS) area website (see <https://wiki.ietf.org/group/ops/yang-security-guidelines>), and that the guidelines there were followed ๐. Security is serious business, bestie ๐ญ.
- IANA Considerations section: This section must always be present ๐. For each module in the document, make sure the IANA Considerations section has entries for these IANA registries:
- XML Namespace Registry: Register the YANG module namespace.
- YANG Module Registry: Register the YANG module name, prefix, namespace, and RFC number, following the rules in [RFC6020] ๐.
- References: Check that the references are split properly into normative and informative ones ๐. RFCs 2119 and 8174 should be normative references if the terminology they define is used in the document ๐. All references the boilerplate requires need to be there, and every YANG module containing imported items needs to be cited as a normative reference. All citations should point to the most current RFCs, unless there's a valid reason otherwise. For example, it's totally fine to include an informative reference to an older version of a spec to explain a feature that's included for backward compatibility ๐ฐ๏ธ. Citations for all imported modules also need to show up somewhere in the document text (outside the YANG module). If a YANG module has "reference" or "description" statements that point to an I-D, then that I-D goes in as an informative reference ๐ง.
- License: Check that the document has the Revised BSD License in each YANG module or submodule. Some guidelines for this are in Section 3.1 ๐. Make sure the correct year shows up in all copyright dates ๐ . Use the approved text from the latest TLP document, found at <https://trustee.ietf.org/license-info/> ๐ .
- Other Issues: Check for any issues listed at <https://www.ietf.org/id-info/checklist.html> that aren't already covered elsewhere ๐.
- Technical Content: Review the actual technical content against the guidelines in this document ๐ง . Using a YANG module compiler is recommended for catching syntax errors ๐ ๏ธ. You can find a list of free tools, plus formatting advice, at <https://wiki.ietf.org/group/netconf> and <https://wiki.ietf.org/group/netmod> โจ.
Checking syntax is only part of the job, though ๐. It's just as important to actually read the YANG module from the point of view of a potential implementor. It's especially important to check that "description" statements are clear and unambiguous enough for interoperable implementations to be built from them ๐.
Appendix B. Template for IETF Modules ๐ง
Here's the template for IETF modules. Copy it and fill in the blanks ๐.
<CODE BEGINS> file "ietf-template@2023-07-26.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 your-wg-name (Expanded WG Name) Working Group";
// update this contact statement with your info
contact
"WG Web: https://datatracker.ietf.org/wg/your-wg-name
WG List: YOUR-WG-NAME <mailto:your-wg-name@ietf.org>
Editor: your-name
<mailto:your-email@example.com>";
// 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) <insert year> 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 Revised BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed: replace 'date-revision' with the module publication date
// the format is (YYYY-MM-DD)
// replace XXXX with actual RFC number and remove
// this note
revision date-revision {
description
"What changed in this revision.";
reference
"RFC XXXX: <Replace With Document Title>";
}
// Authors: Replace RFC IIII with the RFC number and title
// of the RFC that defined the initial version of
// the module and remove this note
revision date-initial {
description
"Initial version.";
reference
"RFC IIII: <Replace With Document Title>";
}
// 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
}
<CODE ENDS>Appendix C. Template for IANA-Maintained YANG Modules ๐ธ
This one's the template for modules that IANA maintains ๐ฆ. Same vibe, different owner ๐.
<CODE BEGINS> file "iana-template@2023-12-08.yang"
module iana-template {
yang-version 1.1;
// replace this string with a unique namespace URN value
namespace "urn:ietf:params:xml:ns:yang:iana-template";
// replace with the assigned prefix
prefix iana-foo;
organization
"Internet Assigned Numbers Authority (IANA)";
contact
"Internet Assigned Numbers Authority
ICANN
12025 Waterfront Drive, Suite 300
Los Angeles, CA 90094
Tel: +1 310 301 5800
<mailto:iana@iana.org>";
description
"This module defines a template for IANA-maintained modules.
Copyright (c) <insert year> 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 Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
All revisions of IETF and IANA published modules can be found
at the YANG Parameters registry group
(https://www.iana.org/assignments/yang-parameters).
The initial version of this YANG module is part of RFC IIII;
see the RFC itself for full legal notices.
// RFC Ed.: replace IIII with actual RFC number and remove
// this note
// If a script is used, complete with the script information
This version of this YANG module was generated from the
corresponding IANA registry using a <script-info>.
// RFC Ed.: replace the IANA_FOO_URL and remove this note
The latest version of this YANG module is available at
<IANA_FOO_URL>.";
// replace with the registry name and the URL of the IANA registry
reference
"Registry Name (URL)";
// replace 'date-revision' with the module publication date
// the format is (YYYY-MM-DD)
revision date-revision {
description
"Indicates the list of changes per Section 4.30.3 of RFC 9907";
reference
"URL of the latest version of the module
(if any) list the authoritative event (e.g., RFC) that
triggered the update to the YANG module";
}
// replace 'date-initial' with the module publication date
// the format is (YYYY-MM-DD)
revision date-initial {
description
"Initial version.";
reference
"URL of the published initial version of the module
RFC IIII: RFC Title";
// RFC Ed.: Update with the RFC number and title
// of the RFC that defined the initial version of
// the module and remove this note
}
// identity statements
// typedef statements
}
<CODE ENDS>Acknowledgments ๐ซถโจ
Bestie, the people in this section are the real MVPs ๐. Huge thanks to Jรผrgen Schรถnwรคlder and Ladislav Lhotka for the discussion and valuable comments ๐. Ladislav gets extra love for sharing the context that led to the design in [RFC9108] ๐ธ.
Thanks to Italo Busi, Benoรฎt Claise, Tom Petch, Randy Presuhn, Martin Bjรถrklund, Acee Lindem, Dale R. Worley, Kent Watsen, Jan Lindblad, Qiufang Ma, Mahesh Jethanandani, Robert Wilton, and Thomas Fossati for the comments ๐ง.
Lou Berger suggested including more details about IANA considerations ๐. Section 4.28 is inspired by [RFC8819] ๐ฆ.
Michal Vaลกko reported an inconsistency in Sections 4.6.2 and 4.6.4 of [RFC8407] ๐. Thanks to Xufeng Liu for reviewing the document, including the YANGDOCTORS reviews ๐ .
Italo Busi provided the examples of "case + when" construct ๐. Thanks to Rich Salz and Michael Richardson for the SAAG review ๐. Kent Watsen contributed text to the security and IANA-maintained YANG module templates ๐.
Special thanks to Amanda Baber for the thoughtful and careful review of the document ๐. Thanks to Qiufang Ma for the careful shepherd review ๐. Thanks to Acee Lindem for kicking off the discussion on data model versus module ๐ฅ. Thanks to Mahesh Jethanandani for the thoughtful AD review ๐ญ.
Thanks to Christer Holmberg for the genart review, Jean Mahoney for the check on RPC implications, Ralf Weber for the dnsdir review, Giuseppe Fioccola for the opsdir review, Joseph Touch for the tsvart review, and Yoav Nir for the secdir review ๐.
Thanks รric Vyncke, Mike Bishop, Roman Danyliw, Orie Steele, Ketan Talaulikar, Deb Cooley, and Gorry Fairhurst for the IESG review ๐.
The author of RFC 8407 is Andy Bierman ๐.
Acknowledgments from RFC 8407: The structure and contents of that 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 that document ๐ฆ.
Authors' Addresses ๐ฌ
Andy Bierman ๐ท YumaWorks United States of America Email: andy@yumaworks.com
Mohamed Boucadair (editor) ๐ Orange France Email: mohamed.boucadair@orange.com
Qin Wu ๐
Huawei China Email: bill.wu@huawei.com
That's a wrap, bestie ๐ฆ๐ you made it through all 17 parts ๐ญ๐
๐ฆ where this page comes from
- ietf: rfc9907 2026-03
- ๐ girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms