<?xml version='1.0'encoding='utf-8'?>encoding='UTF-8'?> <!DOCTYPE rfc [ <!ENTITY nbsp " "> <!ENTITY zwsp "​"> <!ENTITY nbhy "‑"> <!ENTITY wj "⁠"> ]><?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?> <!-- generated by https://github.com/cabo/kramdown-rfc version 1.7.29 (Ruby 3.4.4) --> <?rfc strict="yes"?> <?rfc comments="yes"?> <?rfc docmapping="yes"?><rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" docName="draft-ietf-netmod-rfc8407bis-28" number="9907" category="bcp" consensus="true" submissionType="IETF" obsoletes="8407" updates="8126" tocInclude="true" sortRefs="true" symRefs="true"version="3"> <!-- xml2rfc v2v3 conversion 3.28.1 -->version="3" xml:lang="en"> <front> <title abbrev="Guidelines for YANG Documents">Guidelines for Authors and Reviewers of Documents Containing YANG Data Models</title> <seriesInfoname="Internet-Draft" value="draft-ietf-netmod-rfc8407bis-28"/>name="RFC" value="9907"/> <seriesInfo name="BCP" value="216"/> <author fullname="Andy Bierman"> <organization>YumaWorks</organization> <address> <postal><country>USA</country><country>United States of America</country> </postal> <email>andy@yumaworks.com</email> </address> </author> <author fullname="Mohamed Boucadair" role="editor"> <organization>Orange</organization> <address> <postal> <country>France</country> </postal> <email>mohamed.boucadair@orange.com</email> </address> </author> <author fullname="Qin Wu"> <organization>Huawei</organization> <address> <postal> <country>China</country> </postal> <email>bill.wu@huawei.com</email> </address> </author> <dateyear="2025" month="June" day="05"/> <area>Operations and Management</area> <workgroup>Network Modeling</workgroup>year="2026" month="January"/> <area>OPS</area> <workgroup>netmod</workgroup> <keyword>NETCONF</keyword> <keyword>RESTCONF</keyword> <keyword>Automation</keyword> <abstract><?line 137?><t>This document provides guidelines for authors and reviewers of specifications containing YANG data models, including IANA-maintained YANG modules. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) and RESTCONFProtocolprotocol implementations that utilize YANGmodules. Thismodules.</t> <t>This document obsoletes RFC8407.</t> <t>Also, this document8407; it also updates RFC 8126 by providing additional guidelines for writing the IANA considerations for RFCs that specify IANA-maintained YANG modules.</t> </abstract><note removeInRFC="true"> <name>Discussion Venues</name> <t>Discussion of this document takes place on the Network Modeling Working Group mailing list (netmod@ietf.org), which is archived at <eref target="https://mailarchive.ietf.org/arch/browse/netmod/"/>.</t> <t>Source for this draft and an issue tracker can be found at <eref target="https://github.com/boucadair/rfc8407bis"/>.</t> </note></front> <middle><?line 150?><section anchor="introduction"> <name>Introduction</name> <t>The standardization of network configuration interfaces for use with network configuration management protocols, such as the Network Configuration Protocol (NETCONF) <xref target="RFC6241"/> andtheRESTCONFProtocol<xref target="RFC8040"/>, requires a modular set of data models that can be reused and extended over time.</t> <t>This document defines a set of guidelines for documents containing YANG 1.1 <xref target="RFC7950"/> and YANG 1.0 <xref target="RFC6020"/> data models, including IANA-maintained YANG modules. YANG is used to define the data structures, protocol operations, and notification content used within a NETCONF and/or RESTCONF server. YANG is also used to define abstract data structures <xref target="RFC8791"/>. A NETCONF or RESTCONF server that supports a particular YANG module will support client NETCONF and/or RESTCONF operation requests, as indicated by the specific content defined in the YANG module.</t> <t>Many YANG constructs are defined as optional to use, such as the "description" statement. However, in order to make YANG modules more readable and interoperable, it is desirable to define a set of descriptive usage guidelines that entails a higher level of compliance than the minimum level defined in the YANG specification <xref target="RFC7950"/>.</t> <t>In addition, YANG allows constructs such as infinite length identifiers and string values, or top-level mandatory nodes, that a compliant server is not required to support. Only constructs that all servers are required to support can be used in IETF YANG modules.</t> <!-- [rfced] Note: [RFC6421] uses "Operations layer" and "Content layer" rather than "operations layer" and "content layer". Please let us know if/how to update for consistency. Current: This document defines usage guidelines related to the NETCONF operations layer and NETCONF content layer, as defined in [RFC6241], and the RESTCONF methods and RESTCONF resources, as defined in [RFC8040]. --> <t>This document defines usage guidelines related to the NETCONF operations layer and NETCONF content layer, as defined in <xref target="RFC6241"/>, and the RESTCONF methods and RESTCONF resources, as defined in <xref target="RFC8040"/>.</t> <t>These guidelines are intended to be used by authors and reviewers to improve the readability and interoperability of published YANG data models. These guidelines can be used independent of the IETF Stream of publicationstreamor even by other organizations.</t> <t>YANG 1.0 modules have to conform to <xref target="RFC6020"/> while YANG 1.1 modules have to conform to <xreftarget="RFC7950"/>. Thistarget="RFC7950"/>; this document adds usage guidelines in addition to theseYANGRFCs.</t> <t><xref target="sec-iana-mm"/> updates <xref target="RFC8126"/> by providing guidance for writing the IANAconsiderationsConsiderations sections for RFCs that specify IANA-maintained YANG modules.</t> <t>Note that this document is not a YANGtutorial, andtutorial; the reader is expected to know the YANG data modeling language before implementing the guidance in this document.</t><ul empty="true"> <li> <t>Note to the RFC Editor: Please replace "AAAA" through the document with the RFC number assigned to this document.</t> </li> </ul><section anchor="changes-since-rfc-8407"> <name>Changes Since RFC 8407</name> <!--[rfced] Would you like to move the "Changes Since RFC 8407" section to an appendix? That placement would be more consistent with other RFCs. (Perhaps this was already considered, as we see this was suggested on https://mailarchive.ietf.org/arch/msg/netmod/0Fj8uYw4Tz9GjxOzNoOxYOzJYFQ/) --> <t>The following changes have been made to the guidelines published in <xref target="RFC8407"/>:</t> <ul spacing="normal"> <li> <t>Implemented the following errata5693, 5800, 6899,reports: <xref target="Err5693"/>, <xref target="Err5800"/>, <xref target="Err6899"/>, and7416.</t><xref target="Err7416"/>.</t> </li> <li> <t>Updated the terminology.</t> </li> <li> <t>Added a note about notation conventions.</t> </li> <li> <t>Updated theURLreference information of the IETFauthorsauthor guidelines.</t> </li> <li> <t>Updated the guidance so that the "file name" after the <tt><CODE BEGINS></tt> tag is mandatory.</t> </li> <li> <t>Added code markers for the security template.</t> </li> <li> <t>Updated the YANG security considerations template to better insist on the key secure transport features.</t> </li> <li> <!--[rfced] There is a slight difference between the text in the change log and the text in the document with regard to how RFC 7952 is listed (i.e., is it an example of an RFC that might disqualify a document from needing the Security Considerations template, or are RFC 8791 and 7952 the only RFCs that would do that?). Change log (Original): * Added statements that the security template is not required for modules that follow [RFC8791] or [RFC7952]. Section 3.7 (Original): Unless the modules comply with [RFC8791] or define YANG extensions (e.g., [RFC7952]),... and 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]. --> <t>Added statements that the security template is not required for modules that follow <xref target="RFC8791"/> or <xref target="RFC7952"/>.</t> </li> <li> <t>Added a statement about how to cite the RFCs that are listed in the security template.</t> </li> <li> <t>Added a template for IANA registrations.</t> </li> <li> <t>Added a note that folding of the examples should be done as per the conventions described in <xreftarget="RFC8792"/> conventions.</t>target="RFC8792"/>.</t> </li> <li> <t>Added a recommendation about long trees.</t> </li> <li> <t>Fixed a reference bug in <xref target="sec-module-naming-conventions"/>.</t> </li> <li> <t>Added a recommendation for the use of meaningful prefix values.</t> </li> <li> <t>Added a note thatRFC8792-foldingfolding 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.</t> </li> <li> <t>Added tool validation checks to ensure that YANG modules fit into the line limits of an I-D.</t> </li> <li> <t>Added tool validation checks of JSON-encoded examples.</t> </li> <li> <t>Added a recommendation to ease extracting and validating examples.</t> </li> <li> <t>Updated many examples to be aligned with the consistent indentation recommendation (internal consistency).</t> </li> <li><t>Updated<!--[rfced] Would the following update be agreeable? Original: * Updated the IANA considerations to encourage registration requests to indicate whether a module is maintained by IANA ornot.</t>not. Perhaps: * Updated the guidance for writing IANA Considerations sections to encourage registration requests to indicate whether or not a module is maintained by IANA. --> <t>Updated the IANA considerations to encourage registration requests to indicate whether or not a module is maintained by IANA.</t> </li> <li> <t>Added guidelines for IANA-maintained modules.</t> </li> <li> <t>Added guidelines about the use of the terms "YANG module" and "YANG data model".</t> </li> <li> <t>Elaborated the guidance for the use of values reserved for documentation in examples.</t> </li> <li> <t>Recommended the use of "example:" for URI examples.</t> </li> <li> <t>Added a new section "Defining Standard Tags" (<xref target="sec-tags"/>) to echo the guidance in <xref target="RFC8819"/>.</t> </li> <li> <t>Recommended against the use of "case + when" construct in some cases.</t> </li> <li> <t>Added a discussion about the prefix pattern to use for example modules.</t> </li> <li> <t>Updated the NMDA guidance in the narrative text to highlight modules that are notNMDA-compliant.</t>compliant with NMDA.</t> </li> <li> <t>Added a new section about the classification of YANGmodule classification.</t>modules.</t> </li> <li> <t>Fixed an inconsistency in Section4.6.2<xref target="RFC8407" section="4.6.2" sectionFormat="bare"/> where the example mentionsidentities,identities but uses them without their prefix as per Section4.6.4.</t><xref target="RFC8407" section="4.6.4" sectionFormat="bare"/>.</t> </li> <li> <t>Fixed an inconsistency in Section4.6.4 which fails<xref target="RFC8407" section="4.6.4" sectionFormat="bare"/> that failed to use "derived-from-or-self()" mentioned back inSection 4.6.2.</t><xref target="function-library"/>.</t> </li> <li> <t>Added a new section for modeling abstract data structures.</t> </li> <li> <t>Added a discussion about "must + error-message" constructs for state data.</t> </li> <li> <t>Added text about summary of changes in revision statements.</t> </li> <li> <t>Added a template for IANA-maintained modules.</t> </li> <li> <t>Updated the wiki URLs to use the newstructure instead of the old trac.</t>structure.</t> </li> <li> <t>Added anydata to the list of statements with mandatorydescriptiondescription(s) (<xref target="sec-data-def"/>).</t> </li> <li> <t>Fixed an error (invalid statements) in Section4.24.</t><xref target="RFC8407" section="4.24" sectionFormat="bare"/>.</t> </li> <li><t>Soften<t>Softened genericI-DsI-D authorship guidance.</t> </li> </ul> </section> </section> <section anchor="terminology-notation-conventions"> <name>Terminology&and Notation Conventions</name> <t>Some of the templates defined in the document use "--" to easily identify specific instructions to the authors. Text prefixed with "--" must not be copied as such when using a template. Note that for YANG templates, "//" is used to convey such instructions.</t> <t>RFC IIII is used to refer to an RFC that defines an initial version of an IANA-maintained module.</t> <t>The following terms are used throughout this document:</t><dl><dl spacing="normal" newline="false"> <dt>IANA-maintained module:</dt> <dd> <t>A YANG module that is maintained by IANA and has an IANA registry associated with it (e.g., "iana-tunnel-type" <xref target="RFC8675"/> or "iana-pseudowire-types" <xref target="RFC9291"/>).</t></dd> <dt/> <dd><t>Once an IANA-maintained module is initialized, new values are not directly added to the module. These values are instead added to the companion registry.</t> </dd> <!--[rfced] Section 2: We have the following questions related to the terminology in this section: a) Please review our updates to the following text; based on the text that follows defining "published" and "unpublished", please confirm that this update is accurate (i.e., can an IETF module not exist in an I-D, "IETF module" would only be the terminology used for a published RFC). Original: IETF module: A YANG module that is published by the IETF and that is not maintained by IANA. Current: IETF module: A YANG module that is published as an RFC from the IETF Stream and that is not maintained by IANA. b) Is it possible to have a YANG module that is not IANA-maintained and not an IETF module? If so, should their be some kind of terminology to address that? c) In the following definition of "unpublished", might "unstable publication" be a bit contradictory? Perhaps Original: unpublished: An unstable release of a module or submodule. For example the "Internet-Draft" described in Section 2.2 of [RFC2026] is considered an unstable publication that is a work in progress, subject to change at any time. Perhaps: 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. d) In the "published" and "unpublished" definitions, it seems a bit odd to expand RFC and put Request for Comments and Internet-Draft in quotes. Original: published: A stable release of a module or submodule. For example, the "Request for Comments" described in Section 2.1 of [RFC2026] is considered a stable publication. unpublished: An unstable release of a module or submodule. For example the "Internet-Draft" described in Section 2.2 of [RFC2026] is considered an unstable publication that is a work in progress, subject to change at any time. Perhaps: 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. --> <dt>IETF module:</dt> <dd> <t>A YANG module that is publishedbyas an RFC from the IETF Stream and that is not maintained by IANA.</t> </dd> <dt>published:</dt> <dd> <t>A stable release of a module or submodule. For example, the "Request for Comments" described in <xref section="2.1" sectionFormat="of" target="RFC2026"/> is considered a stable publication.</t> </dd> <dt>unpublished:</dt> <dd> <t>An unstable release of a module or submodule. Forexampleexample, the "Internet-Draft" described in <xref section="2.2" sectionFormat="of" target="RFC2026"/> is considered an unstable publication that is a work inprogress,progress and is subject to change at any time.</t> </dd> <dt>YANG fragment:</dt> <dd> <t>A set of YANG statements thatareis not intended to represent a complete YANG module or submodule. These statements are not intended for actual use, except to provide an example of YANG statement usage. The invalid syntax "..." is sometimes used to indicate that additional YANG statements would be present in a real YANG module.</t> </dd> <dt>YANG tree diagram:</dt> <dd> <t>A diagram representing the contents of a YANG module, as defined in <xref target="RFC8340"/>. It is also called a "tree diagram".</t> </dd> </dl> <section anchor="netconf-terms"> <name>NETCONF Terms</name> <t>The following terms are defined in <xref target="RFC6241"/> and are not redefined here:</t> <!-- [rfced] FYI - we note that [RFC6241] defines "capability" rather than "capabilities" and "protocol operation" rather than "operation". Please let us know if/how to update for consistency. Current: The following terms are defined in [RFC6241] and are not redefined here: * capabilities * client * operation * server Perhaps: The following terms are defined in [RFC6241] and are not redefined here: * capability * client * protocol operation (or simply "operation") * server --> <ul spacing="normal"> <li> <t>capabilities</t> </li> <li> <t>client</t> </li> <li> <t>operation</t> </li> <li> <t>server</t> </li> </ul> </section> <section anchor="yang-terms"> <name>YANG Terms</name> <t>The following terms are defined in <xref target="RFC7950"/> and are not redefined here:</t> <ul spacing="normal"> <li> <t>data node</t> </li> <li> <t>module</t> </li> <li> <t>namespace</t> </li> <li> <t>submodule</t> </li> <li> <t>version</t> </li> <li> <t>YANG</t> </li> <li> <t>YIN</t> </li> </ul> <t>Note that the term'module'"module" may be used as a generic term for a YANG module or submodule. When describing properties that are specific to submodules, the term'submodule'"submodule" is used instead.</t> </section> <section anchor="network-management-datastore-architecture-nmda-terms"> <name>Network Management Datastore Architecture (NMDA) Terms</name> <t>The following terms are defined in <xref target="RFC8342"/> and are not redefined here:</t> <ul spacing="normal"> <li> <t>configuration</t> </li> <li> <t>conventional configuration datastore</t> </li> <li> <t>datastore</t> </li> <li> <t>operational state</t> </li> <li> <t>operational state datastore</t> </li> </ul> </section> <section anchor="requirements-notation"> <!--[rfced] Might it be possible to swap Sections 2.4 and 2.5? Reasoning: Sections 2.1 - 2.3 are all YANG-terminology related, and so is Section 2.5. The boilerplate in Section 2.4 seems to interrupt that. Suggested: 2. Terminology and Notation Conventions 2.1. NETCONF Terms 2.2. YANG Terms 2.3. Network Management Datastore Architecture (NMDA) Terms 2.4. YANG Data Model versus YANG Module 2.5. Requirements Notation --> <name>Requirements Notation</name><t>The<t> The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they appear in all capitals, as shownhere.</t> <?line -18?>here. </t> </section> <section anchor="yang-data-model-vs-yang-module"> <name>YANG Data Modelvs.versus YANG Module</name> <t>Both <xref target="RFC6020"/> and <xref target="RFC7950"/> make a distinction between the following concepts:</t><dl><dl spacing="normal" newline="false"> <dt>data model:</dt> <dd> <t>Describes how data is represented and accessed.</t></dd> <dt/> <dd><t>YANG structures data models into modules for ease of use <xref target="RFC8309"/>.</t> </dd> <dt>module:</dt> <dd> <t>Defines hierarchies of schema nodes to make a self-contained and compilable block of YANG definitions and inclusions.</t></dd> <dt/> <dd><t>A YANG module is typically a single ".yang" file, starting with a "module" statement.</t></dd> <dt/> <dd><t>A YANG module may include any number of submodules that are stored in separate ".yang" files starting with a "submodule" statement. Regardless of the presence of submodules, the module and its submodules are externally viewed as a single YANG module.</t> </dd> </dl> <t>A YANG data model can consist(1) of aof:</t> <ol> <li>a single YANG module (e.g., <xref target="RFC9129"/>)or (2) multipleor</li> <li>multiple YANG modules (e.g., <xreftarget="RFC7407"/>).</t>target="RFC7407"/>).</li></ol> <t>Note that the term "YANG model" is sometimes used as an abbreviation ofYANG"YANG datamodel.model". However, that term should be avoided in favor ofYANG"YANG datamodel.model". Likewise, "YANG data module" has no meaning and must be avoided.</t> <t>Even if a YANG data model is structured as a single YANG module,YANG data modelthe 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".</t> </section> </section> <section anchor="general-documentation-guidelines"> <name>General Documentation Guidelines</name> <!--[rfced] Would you like to clarify "under review" here, or mention (anywhere in the document) who is reviewing the YANG module? We note that Appendix A mentions being reviewed for "technical correctness and adherence to IETF documentation requirements". Original: YANG modules under review are likely to be contained in Internet-Drafts (I-Ds). Perhaps: YANG modules being considered for publication in an RFC are contained in Internet-Drafts (I-Ds). --> <t>YANG modules under review are likely to be contained in Internet-Drafts (I-Ds). Guidelines for authoring an I-Dauthorscan be found at <xref target="ID-Guidelines"/>. These guidelines are not repeated here.</t> <t>The following sections <bcp14>MUST</bcp14> be present in an I-D or RFC containing a YANG module:</t> <ul spacing="normal"> <li> <t>Narrative sections (<xref target="sec-narrative"/>)</t> </li> <li><t>Definitions<!--[rfced] Should this text be updated to indicate that there can be more than one definitions section? (e.g., RFC 8776 contains modules in Sections 4 and 5.) Original: The following sections MUST be present in an I-D or RFC containing a YANG module: * Narrative sections (Section 3.5) * Definitions section (Section 3.6) Perhaps: The following sections MUST be present in an I-D or RFC containing one or more YANG modules: * Narrative sections (Section 3.5) * Definitions section(s) (Section 3.6) In Section 3.6: Original: This section contains the module(s) defined by the specification. Perhaps: One or more sections contain the module(s) defined by the specification. --> <t>A Definitions section (<xref target="sec-def"/>)</t> </li> </ul> <t>Additional YANG-specific considerations <bcp14>MUST</bcp14> be included for the following sections:</t> <ul spacing="normal"> <li> <t>Security Considerationssection(<xref target="sec-sec-cons-sec"/>)</t> </li> <li> <t>IANA Considerationssection(<xref target="sec-iana-cons"/>)</t> </li> <li> <t>Referencessection(<xref target="sec-ref"/>)</t> </li> </ul> <t>There are three usage scenarios for YANG that can appear in an I-D or RFC:</t> <ul spacing="normal"> <li> <t>normative module or submodule</t> </li> <li> <t>example module or submodule</t> </li> <li> <t>example YANG fragment that is not part of any module or submodule</t> </li> </ul><t>The<!--[rfced] Will the reader know when the guidelines are applicable to example modules and fragments? If not, where can they get more information to guide them? Original: The guidelines in this document refer mainly to a normative module or submodule but may be applicable to example modules and YANG fragments as well. --> <t>The guidelines in this document refer mainly to a normative module or submodule, but they may be applicable to example modules and YANG fragments as well.</t> <section anchor="module-copyright"> <name>Module Copyright</name> <t>The module "description" statement <bcp14>MUST</bcp14> contain a reference to the latest approved IETF Trust Copyright statement, which is availableonline at:</t> <artwork><![CDATA[ <https://trustee.ietf.org/license-info/> ]]></artwork>at: <eref target="https://trustee.ietf.org/license-info/" brackets="angle"/>.</t> </section> <section anchor="code-components"> <name>Code Components</name> <t>Each normative YANG module or submodule contained within an I-D or RFC is considered to be a code component. The strings <tt>"<CODE BEGINS>" and "<CODE ENDS>"</tt> <bcp14>MUST</bcp14> be used to identify each code component.</t> <t>The <tt>"<CODE BEGINS>"</tt> tag <bcp14>MUST</bcp14> be followed by a string identifying the file name specified in <xref section="5.2" sectionFormat="of" target="RFC7950"/>. The name string form that includes the revision date <bcp14>SHOULD</bcp14> be used. The revision date <bcp14>MUST</bcp14> match the date used in the most recent revision of the module.</t> <t>The following example is for the "2016-03-20" revision of the "ietf-foo" module:</t> <sourcecodetype="yang"><![CDATA[ <CODE BEGINS>name="" type="yang" markers="true"><![CDATA[ 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>]]></sourcecode> <section anchor="example-modules"> <name>Example Modules</name> <t>Example modules are not code components. The <tt><CODE BEGINS></tt> convention <bcp14>MUST NOT</bcp14> be used for example modules. However, example modules <bcp14>MUST</bcp14> be validated (<xref target="sec-tools"/>).</t> <t>An example module <bcp14>SHOULD</bcp14> be named using the term "example", followed by a hyphen, followed by a descriptive name, e.g., "example-toaster".</t> <t>See <xref target="sec-namespace-assignments"/> regarding the namespace guidelines for example modules.</t> </section> </section> <section anchor="terminology-section"> <name>Terminology Section</name> <t>A terminology section <bcp14>MUST</bcp14> be present if any terms are defined in the document or if any terms are imported from other documents.</t> </section> <section anchor="tree-diagrams"> <name>Tree Diagrams</name> <t>YANG tree diagrams provide a concise representation of a YANG module and <bcp14>SHOULD</bcp14> be included to help readers understand YANG module structure. Guidelines on tree diagrams can be found in <xref section="3" sectionFormat="of" target="RFC8340"/>. Tree diagrams longer than one page <bcp14>SHOULD</bcp14> be included in an appendix, i.e., not in the main body of the document.</t> <t>If YANG tree diagrams are used, then an informative reference to the YANG tree diagrams specification <bcp14>MUST</bcp14> be included in the document. Refer to <xref section="2.2" sectionFormat="of" target="RFC8349"/> for an example of such a reference.</t> </section> <section anchor="sec-narrative"> <!--[rfced] May we update "narrative part" to "narrative sections" in the following for consistency? Original: The narrative part MUST include an overview section that describes the scope and field of application of the data model(s) defined by the specification and that specifies the relationship (if any) of these data models to other standards, particularly to standards containing other YANG data models. Perhaps: 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 and that specifies the relationship (if any) of these data models to other standards, particularly to standards containing other YANG data models. --> <name>Narrative Sections</name> <t>The narrative part <bcp14>MUST</bcp14> include an overview section that describes the scope and field of application of the data model(s) defined by the specification and that specifies the relationship (if any) of these data models to other standards, particularly to standards containing other YANG data models. The narrative part <bcp14>SHOULD</bcp14> include one or more sections to briefly describe the structure of the data models defined in the specification.</t> <!--[rfced] The subject/verb agreement here is difficult to follow. Would the suggested update below correctly convey your meaning? Original: If the module or modules defined by the specification imports definitions from other modules (except for those defined in [RFC7950] or [RFC6991]) or are always implemented in conjunction with other modules, then those facts MUST be noted in the overview section; any special interpretations of definitions in other modules MUST be noted as well. Perhaps: If the module (or modules) defined by the specification imports definitions from other modules (except for those defined in [RFC7950] or [RFC6991]) or is always implemented in conjunction with other modules, then those facts MUST be noted in the overview section; any special interpretations of definitions in other modules MUST be noted as well. --> <t>If the module or modules defined by the specification imports definitions from other modules (except for those defined in <xref target="RFC7950"/> or <xref target="RFC6991"/>) or are always implemented in conjunction with other modules, then those facts <bcp14>MUST</bcp14> be noted in the overview section; any special interpretations of definitions in other modules <bcp14>MUST</bcp14> be noted as well. Refer to <xref section="2.3" sectionFormat="of" target="RFC8349"/> for an example of this overview section.</t> <t>If the document contains major Network Management Datastore Architecture (NMDA) exceptions orincludeincludes a temporary non-NMDA module <xref target="RFC8342"/>, then the Introduction section <bcp14>SHOULD</bcp14> mention this fact with the reasoning that motivated that design. Refer to <xref target="sec-op-state"/> for more NMDA-related guidance. Specifically, <xref target="sec-4.23.2"/> includes a recommendation for designers to describe and justify any NMDA exceptions in detail as part of the module itself.</t> <t>Consistent indentation <bcp14>SHOULD</bcp14> be used for all examples, including YANG fragments and protocol message instance data. If line wrapping isdoneused for formatting purposes, then this <bcp14>SHOULD</bcp14> be indicated per the guidance in <xref target="RFC8792"/>, as shown in the following example:</t> <artwork><![CDATA[ =============== 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> ]]></artwork> <t>Built-in YANG features (e.g., breaking line, "+") <bcp14>SHOULD</bcp14> be used to fit a module into the line limits. Exceptionally,RFC8792-folding ofYANG modules <bcp14>MAY</bcp14> beusedfolded as described in RFC 8792 if and only if built-in YANG features are not sufficient. A similar approach (e.g.,useusing "--tree-line-length 69" orsplitsplitting a tree into subtrees) <bcp14>SHOULD</bcp14> be followed for tree diagrams.</t> <section anchor="yang-module-classification"> <name>YANG Module Classification</name> <t>The narrative section <bcp14>SHOULD</bcp14> include a mentionaboutof the classification of a given model. Such a mention is meant to ease positioning the module in the overall operational ecosystem. Specifically, the following types from <xref target="RFC8309"/> and <xref target="RFC8969"/> can be used:</t> <dl> <dt>Service Model:</dt> <dd> <t>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.</t> </dd> <dt/> <dd> <t>Examples of service models are the L3VPN Service Model (L3SM) <xref target="RFC8299"/> and the L2VPN Service Model (L2SM) <xref target="RFC8466"/>.</t> </dd> <dt>Network Model:</dt> <dd> <t>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 <xref target="RFC8309"/>.</t> </dd> <dt/> <dd><t>It<t>This model can be used by a network operator to allocate resources (e.g., a tunnelresource,resource or a topology resource) for the service or to schedule resources to meet the service requirements defined in a service model.</t> </dd> <dt/> <dd> <t>Examples of network models are the L3VPN Network Model (L3NM) <xref target="RFC9182"/> or the L2VPN Network Model (L2NM) <xref target="RFC9291"/>.</t> </dd> <dt>Device Model:</dt> <dd> <t>Refers to the Network Element YANG data model described in <xref target="RFC8199"/> or the device configuration model discussed in <xref target="RFC8309"/>.</t> </dd> <dt/> <dd> <t>Device models are also used to model a function embedded in a device (e.g., Access Control Lists (ACLs) <xref target="RFC8519"/>).</t> </dd> <dt/> <dd><t>A<!-- [rfced] FYI, we updated "4.2" to "A.4.2" here, as [RFC8969] does not have an Appendix 4.2, but does have an Appendix A.4.2. Please let us know if this is not accurate. We note that A.4.2 (Device Management) uses 'YANG modules' rather than 'models'. Perhaps A.4.4 (Some Device Model Examples) was intended? However, it notes notes the list is not comprehensive. Original: A comprehensive list of device models is provided in Appendix 4.2 of [RFC8969]. Current: A comprehensive list of device models is provided in Appendix A.4.2 of [RFC8969]. Perhaps: A non-comprehensive list of device models is provided in Appendix A.4.4 of [RFC8969]. --> <t>A comprehensive list of device models is provided in <xreftarget="RFC8969"/>.</t>target="RFC8969" section="A.4.2"/>.</t> </dd> </dl> </section> </section> <section anchor="sec-def"> <name>Definitions Section</name> <t>This section contains the module(s) defined by the specification. These modules <bcp14>SHOULD</bcp14> be written using the YANG 1.1 <xref target="RFC7950"/> syntax. YANG 1.0 <xref target="RFC6020"/> syntax <bcp14>MAY</bcp14> 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 <bcp14>MUST</bcp14> be written using YANG 1.1.</t> <t>AYINYANG Independent Notation (YIN) syntax version (<xref section="13" sectionFormat="of" target="RFC7950"/>) of the module <bcp14>MAY</bcp14> also be present in the document. There <bcp14>MAY</bcp14> also be other types of modules present in the document, such as Structure of Management Information Version 2 (SMIv2), which are not affected by these guidelines.</t> <!--[rfced] Regarding the statements about keywords from BCP 14, may we update the second part to use the same term ("keywords")? Specifically, may we replace "all-uppercase reserved words" with "keywords"? Original: ...within a YANG module are considered normative. The use of keywords defined in [RFC2119] and [RFC8174] apply to YANG "description" statements in normative modules exactly as they would in any other normative section. and Example YANG modules and example YANG fragments MUST NOT contain any normative text, including any all-uppercase reserved words from [RFC2119] and [RFC8174]. Perhaps: Example YANG modules and example YANG fragments MUST NOT contain any normative text, including any keywords from [RFC2119] and [RFC8174]. --> <t>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 <xref target="RFC2119"/> and <xref target="RFC8174"/> apply to YANG "description" statements in normative modules exactly as they would in any other normative section.</t> <t>Example YANG modules and example YANG fragments <bcp14>MUST NOT</bcp14> contain any normative text, including any all-uppercase reserved words from <xref target="RFC2119"/> and <xref target="RFC8174"/>.</t> <t>Consistent indentation and formatting (e.g., folding) <bcp14>SHOULD</bcp14> be used in all YANG statements within a module.</t> <t>See <xref target="sec-usage-guidelines"/> for guidelines on YANG usage.</t> </section> <section anchor="sec-sec-cons-sec"> <name>Security Considerations Section</name> <t>Each specification that defines one or more modules <bcp14>MUST</bcp14> contain a section that discusses security considerations relevant to those modules.</t> <!--[rfced] Regarding Section 3.7: a) This text seems redundant. Please let us know if/how this section should be updated. Original: Unless the modules comply with [RFC8791] or define YANG extensions (e.g., [RFC7952]), the security section MUST be modeled after the latest approved template (available at <https://wiki.ietf.org/group/ops/yang-security-guidelines>). and 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]. b) Looking at the citations to RFC 7952 in Section 3.7, the first mention calls it an example, while the later mention and the related entry in the change log seem more definitive. Are there other RFCs that define YANG extensions or should the example indication be removed? Please review and advise. Section 3.7 (Original): Unless the modules comply with [RFC8791] or define YANG extensions (e.g., [RFC7952]),... and 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]. Change log (Original): * Added statements that the security template is not required for modules that follow [RFC8791] or [RFC7952]. --> <!--[rfced] Regarding Sections 3.7 and 3.7.1 (Security Considerations Section Template): a) We note the the following text was removed from Section 3.7 between RFC 8407 and this document: Section 3.7.1 contains the security considerations template dated 2013-05-08 and last updated on 2018-07-02. As the template listed at https://wiki.ietf.org/group/ops/yang-security-guidelines is likely to continue to evolve ("latest approved template"), should there be some mention here that Section 3.7.1 is a snapshot of the template that is available in the wiki at the time of writing in order to avoid author confusion? b) With point (a) in mind, would it make sense to begin Section 3.7.1 (prior to <CODE BEGINS> with a note mentioning that what follows is a snapshot and authors should go to <https://wiki.ietf.org/group/ops/yang-security-guidelines> for the most up-to-date version (i.e., might someone just look up Section 3.7.1, without seeing 3.7, and not realize there are differences)? c) There are some minor differences between Section 3.7.1 and the wiki page. Should this document be updated to match the wiki? In addition to the differences between square and angle brackets, we see the following: i) Section numbering difference: This document: This section is modeled after the template described in Section 3.7 The wiki: This section is modeled after the template described in Section 3.7.1 ii) Numbering and textual differences: This document: These YANG-based management protocols (1) have to use a secure transport layer (e.g., SSH [RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use mutual authentication. The wiki: These protocols have to use a secure transport layer (e.g., SSH [RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and have to use mutual authentication. iii) Use of "reasonably": This document: All writable data nodes are likely to be sensitive or vulnerable in some network environments. The wiki: All writable data nodes are likely to be reasonably sensitive or vulnerable in some network environments. d) Might it make the template in Section 3.7.1 more easily usable to authors if it were numbered? That is: 1. Writable nodes section: 2. Readable nodes section: 3. RPC/action operations section: 4. Reusable groupings from other modules section: 5. No data nodes section: (If added, this numbering would appear in this document and the wiki page, not in the RFCs that make use of the template, as they typically do not include these section names.) e) Is it clear to authors how to approach the security considerations section for documents that contain more than one YANG module that might have different security considerations template applications? Should they include subsections of the Security Considerations section for each module? f) The following abbreviations (that are not denoted as well-known at https://www.rfc-editor.org/rpc/wiki/doku.php?id=abbrev_list) are used in the template in Section 3.7.1 and/or at https://wiki.ietf.org/group/ops/yang-security-guidelines without expansion. As this may be the first use of these abbreviations in a document in which this text is inserted, should they be expanded? NETCONF (a bit odd since RESTCONF has no expansion) SSH RPC g) A formatting question/suggestion inspired by the aesthetics of https://wiki.ietf.org/group/ops/yang-security-guidelines but also applicable to the template in Section 3.7.1: Should the quoted text like "There are no particularly sensitive writeable data nodes." actually appear under the blue bubble to match the way the text above was formatted (e.g., "There are a number of data nodes defined...")? So that the comments/blue bubbles are saying something like "If X is true, insert:" and the actual text to insert is not in the comment? h) We see the template gives instructions on what to include: -if a YANG module contains something (e.g., writeable nodes), -if the YANG module contains something particularly sensitive, and -if NO data nodes at all are included. However, is there ever a case where just one (or two) of the sections in this template might not apply (e.g., readable nodes exist but no writable ones do)? If so, will it be clear to authors how to handle that case? For example, should an instruction to include something like "There are no writable data nodes in this YANG module." be included? i) Following on with point (h) above, Section 3.7 states that YANG modules that comply with [RFC8791] or define YANG extensions (e.g., [RFC7952]) do not need to model their Security Considerations sections after the template. However, does it make sense to update the template (and https://wiki.ietf.org/group/ops/yang-security-guidelines) with text instructing authors to overtly mention that the YANG module complies with [RFC8791] or defines YANG extensions and thus the security considerations at https://wiki.ietf.org/group/ops/yang-security-guidelines do not apply? j) Might it be helpful to move the note (about references) at the end of Section 3.7.1 to match its placement at https://wiki.ietf.org/group/ops/yang-security-guidelines? k) Is "that" missing in the first sentence of the second comment in the "Readable nodes section:"? That is, if you remove the parenthetical, you would get: "You must evaluate whether the data model contains any readable data nodes [snip] are particularly sensitive..." l) In the "Readable nodes section:", it could be read as the right course of action would be to include: "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: There are no particularly sensitive readable data nodes." However, perhaps the intended meaning is to either have the first paragraph or have the last sentence? Or, is it the case that some YANG modules have sensitive data nodes that are not "particularly" sensitive? Please review. m) For the following sentence, a reader may expect "remind" to be a transitive verb (with object). May we rewrite as follows? Original: 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 to remind the specific sensitivity or vulnerability of reused nodes. Perhaps: 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 the reused nodes. --> <t>Unless the modules comply with <xref target="RFC8791"/> or define YANG extensions (e.g., <xref target="RFC7952"/>), the security section <bcp14>MUST</bcp14> be modeled after the latest approved template (available at<tt><https://wiki.ietf.org/group/ops/yang-security-guidelines></tt>).<eref target="https://wiki.ietf.org/group/ops/yang-security-guidelines" brackets="angle"/>). <xref target="sec-security-template"/> contains the security considerations template. Authors <bcp14>MUST</bcp14> check the web page at the URL listed above in case there is a more recent version available.</t> <t>In particular:</t> <ul spacing="normal"> <li> <t>Writable data nodes that could be especially disruptive if abused <bcp14>MUST</bcp14> be explicitly listed by name, and the associated security risks <bcp14>MUST</bcp14> be explained.</t> </li> <li> <t>Readable data nodes that contain especially sensitive information or that raise significant privacy concerns <bcp14>MUST</bcp14> be explicitly listed by name, and the reasons for the sensitivity/privacy concerns <bcp14>MUST</bcp14> be explained.</t> </li> <li> <t>Operations (i.e., YANG "rpc" statements) that are potentially harmful to system behavior or that raise significant privacy concerns <bcp14>MUST</bcp14> be explicitly listed by name, and the reasons for the sensitivity/privacy concerns <bcp14>MUST</bcp14> be explained.</t> </li> </ul> <t>Documents that exclusively define modules that follow the extension in <xref target="RFC8791"/> are not required to include the security template in <xref target="sec-security-template"/>. Likewise, following the template is not required for modules that define YANG extensions such as <xref target="RFC7952"/>.</t> <section anchor="sec-security-template"> <name>Security Considerations Section Template</name><sourcecode markers="true"><![CDATA[<artwork><![CDATA[ <CODE BEGINS> X. Security Considerations This section is modeled after the template described in Section 3.7 of[RFCAAAA].[RFC9907]. The "<module-name>" YANG module defines a data model that is designed to be accessed via YANG-based management protocols, such as NETCONF [RFC6241] and RESTCONF [RFC8040]. These YANG-based management protocols (1) have to use a secure transport layer (e.g., 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. -- 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) 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 to remind -- 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').]]></sourcecode> <dl> <dt>Note:</dt> <dd> <t><xref<CODE ENDS> ]]></artwork> <aside><t>Note: <xref target="RFC8341"/> (or a future RFC that replaces it) <bcp14>MUST</bcp14> be listed as a normative reference.</t></dd> <dt/> <dd><t>By default, <xref target="RFC4252"/>, <xref target="RFC6241"/>, <xref target="RFC8040"/>, <xref target="RFC8446"/>, <xref target="RFC9000"/>, and RFCAAAA9907 (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 YANGmodule.</t> </dd> </dl>module.</t></aside> </section> </section> <section anchor="sec-iana-cons"> <name>IANA Considerations Section</name> <t>Each normative YANG module <bcp14>MUST</bcp14> be registered in both the "IETF XML Registry" group <xref target="RFC3688"/> <xref target="IANA-XML"/> and the "YANG Module Names" registry <xref target="RFC6020"/> <xref target="IANA-MOD-NAMES"/>. The registration request in the "YANG Module Names" registry should indicate whether or not the module isIANA-maintained or not.IANA-maintained. This applies to new modules and updated modules. An example of an update registration for the "ietf-template" module can be found in <xref target="sec-iana"/>.</t> <t>Additional IANA considerations applicable to IANA-maintained modules (including instructions to maintain them) are provided in <xref target="sec-iana-mm"/>.</t> <section anchor="documents-that-create-a-new-namespace"> <name>Documents That Create a New Namespace</name> <t>If an I-D defines a new namespace that is to be administered by the IANA, then the document <bcp14>MUST</bcp14> include an IANA Considerations section that specifies how the namespace is to be administered.</t> <t>Specifically, if any YANG module namespace statement value contained in the document is not already registered with IANA, then a new entry in the "ns" registry within the "IETF XML Registry" registry group <bcp14>MUST</bcp14> be requested from the IANA.</t> <t>A registration template for new YANG modules is provided in <xref target="sec-reg-def-iana"/>.</t> </section> <section anchor="documents-that-extend-an-existing-namespace"> <name>Documents That Extend an Existing Namespace</name> <t>It is possible to extend an existing namespace using a YANG submodule that belongs to an existing module already administered by IANA. In this case, the document containing the main module <bcp14>MUST</bcp14> be updated to use the latest revision of the submodule.</t> </section> <section anchor="registration-templates"> <name>Registration Templates</name> <section anchor="sec-reg-def-iana"> <name>IANA Template for Documents Defining New YANG Modules</name> <t>A registration template for a new module is provided below:</t> <artwork><![CDATA[ IANA is requested to register the following URI in the "ns" registry within the "IETF XML Registry" group [RFC3688]: URI: Registrant Contact: TheIESG.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: ]]></artwork>Reference:]]></artwork> </section> <section anchor="iana-template-for-revising-yang-modules"> <name>IANA Template for Revising YANG Modules</name> <t>A registration template for a revised module is provided below:</t> <artwork><![CDATA[ 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: TheIESG.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: ]]></artwork>Reference:]]></artwork> </section> </section> </section> <section anchor="sec-ref"> <name>References Sections</name> <t>For every import or include statement that appears in a module contained in the specification that identifies a module in a separate document, a corresponding normative reference to that document <bcp14>MUST</bcp14> appear in the Normative References section. The reference <bcp14>MUST</bcp14> correspond to the specific module version actually used within the specification.</t> <t>For every normative reference statement that appears in a module contained in the specification that identifies a separate document, a corresponding normative reference to that document <bcp14>SHOULD</bcp14> appear in the Normative References section. The reference <bcp14>SHOULD</bcp14> correspond to the specific document version actually used within the specification. If the reference statement identifies an informative reference that identifies a separate document, a corresponding informative reference to that document <bcp14>MAY</bcp14> appear in the Informative References section.</t> </section> <section anchor="sec-tools"> <name>Validation Tools</name> <t>All modules need to be validated before submission in an I-D. The 'pyang' YANG compiler is freely available fromGitHub:</t> <artwork><![CDATA[ <https://github.com/mbj4668/pyang> ]]></artwork>GitHub: <eref target="https://github.com/mbj4668/pyang" brackets="angle"/>.</t> <t>If the 'pyang' compiler is used to validate a normative module, then the "--ietf" command-line option <bcp14>MUST</bcp14> be used to identify any IETF guideline issues.</t> <t>If the 'pyang' compiler is used to validate an example module, then the "--ietf" command-line option <bcp14>MAY</bcp14> be used to identify any IETF guideline issues.</t> <t>To ensure that a module fits into the line limits of an I-D, the command "pyang -f yang --keep-comments --yang-line-length 69" should be used.</t> <t>The "yanglint" program is also freely available fromGitHub.</t> <artwork><![CDATA[ <https://github.com/CESNET/libyang> ]]></artwork>GitHub: <eref target="https://github.com/CESNET/libyang" brackets="angle"/>.</t> <t>This tool can be used to validate XPath statements within YANG modules.</t> <t>To check that JSON-encoded examples <xref target="RFC7951"/> comply with the target data models, programs such as "yangson" or "yanglint" should be used. Both programs are freely available fromGitHub.</t> <artwork><![CDATA[ <https://github.com/CZ-NIC/yangson> <https://github.com/CESNET/libyang> ]]></artwork>GitHub: <eref target="https://github.com/CZ-NIC/yangson" brackets="angle"/> and <eref target="https://github.com/CESNET/libyang" brackets="angle"/>.</t> </section> <section anchor="module-extraction-tools"> <name>Module Extraction Tools</name> <t>A version of 'rfcstrip' that will extract YANG modules from an I-D or RFC isavailable. The 'rfcstrip' tool that supports YANG module extraction isfreely availableat:</t> <artwork><![CDATA[ <https://github.com/mbj4668/rfcstrip> ]]></artwork>at: <eref target="https://github.com/mbj4668/rfcstrip" brackets="angle"/>.</t> <t>This tool can be used to verify that the <tt>"<CODE BEGINS>"</tt> and <tt>"<CODE ENDS>"</tt> tags are used correctly and that the normative YANG modules can be extracted correctly.</t> <t>The 'xym' tool is freely available on GitHub and can be used to extract YANG modules from adocument.</t> <artwork><![CDATA[ <https://github.com/xym-tool/xym> ]]></artwork>document: <eref target="https://github.com/xym-tool/xym" brackets="angle"/>.</t> </section> <section anchor="module-usage-examples"> <name>Module Usage Examples</name> <t>Each specification that defines one or more modules <bcp14>SHOULD</bcp14> contain usage examples, either throughout the document or in an appendix. This includes example instance document snippets in an appropriate encoding (e.g., XML and/or JSON) to demonstrate the intended usage of the YANG module(s). Examples <bcp14>MUST</bcp14> be validated (<xref target="sec-tools"/>). Refer to <xref target="sec-tools"/> for tools that validate YANG modules and examples. If IP addresses/prefixes are used, then a mix of either IPv4 and IPv6 addresses/prefixes or IPv6 addresses/prefixes exclusively <bcp14>SHOULD</bcp14> be used in the examples.</t> <t>For some types (IP addresses, domain names, etc.), the IETF has reserved values for documentation use. Authors <bcp14>SHOULD</bcp14> use these reserved values in the usage examples if these types are used. Examples of reserved values are listed below:</t> <ul spacing="normal"> <li> <t>IPv4 and IPv6 addresses/prefixes reserved for documentation are defined in <xref target="RFC5737"/>, <xref target="RFC3849"/>, and <xref target="RFC9637"/>.</t> </li> <li> <t>The Enterprise Number 32473 reserved for documentation use is defined in <xref target="RFC5612"/>.</t> </li> <li> <t>Autonomous System Numbers (ASNs) reserved for documentation use are defined in <xref target="RFC5398"/>.</t> </li> <li> <t>Reserved domain names for documentation are defined in <xref target="RFC2606"/>.</t> </li> </ul> <t>URI examples <bcp14>SHOULD</bcp14> be prefixed with "example:".</t> <t>In order to ease extraction and validation of examples, it is <bcp14>RECOMMENDED</bcp14> to use code markers.</t> </section> </section> <section anchor="sec-usage-guidelines"> <name>YANG Usage Guidelines</name> <t>Modules in IETF Standards Track specifications <bcp14>MUST</bcp14> comply with all syntactic and semantic requirements of YANG 1.1 <xref target="RFC7950"/>. See the exception for YANG 1.0 inSection 3.6.<xref target="sec-def"/>. The guidelines in this section are intended to supplement the YANG specification <xref target="RFC7950"/>, which is intended to define a minimum set of conformance requirements.</t> <t>In order to promote interoperability and establish a set of practices based on previous experience, the following sections establish usage guidelines for specific YANG constructs.</t> <t>Only guidelines that clarify or restrict the minimum conformance requirements are included here.</t> <t>A template for IETF modules is provided in <xref target="tem-ietf"/>.</t> <section anchor="sec-module-naming-conventions"> <name>Module Naming Conventions</name> <t>Normative modules contained in Standards Track documents <bcp14>MUST</bcp14> be named according to the guidelines in the IANA Considerations section of <xref target="RFC6020"/>.</t> <t>A distinctive word or abbreviation (e.g., protocol name or working group abbreviation) <bcp14>SHOULD</bcp14> be used in the module name. If new definitions are being defined to extend one or more existing modules, then the same word or abbreviation should be reused, instead of creating a new one.</t> <t>All published module names <bcp14>MUST</bcp14> be unique. For a YANG module published in an RFC, this uniqueness is guaranteed by IANA (<xref section="14" sectionFormat="of" target="RFC6020"/>). For unpublished modules, the authors need to check that no other work in progress is using the same module name.</t> <t>Example modules are non-normative and <bcp14>SHOULD</bcp14> be named with the prefix "example-".</t> <t>It is suggested that a stable module name prefix be selected that represents the entire organization. All normative YANG modules published by the IETF <bcp14>MUST</bcp14> begin with the prefix "ietf-". All IANA-maintained YANG modules <bcp14>MUST</bcp14> begin with the prefix "iana-". Another standards organization, such as the IEEE, might use the prefix "ieee-" for all YANG modules.</t> <t>Once a module name is published, it <bcp14>MUST NOT</bcp14> be reused, even if the RFC containing the module is reclassified to "Historic" status. A module name cannot be changed in YANG, and this would be treated as a new module, not a name change.</t> </section> <section anchor="prefixes"> <name>Prefixes</name> <t>All YANG definitions are scoped by the module containing the definition being referenced. This allows the same name to be used in multiple modules, even if the names are not unique. In the example below, the identifier "foo" is used in all three modules:</t> <!--[rfced] Regarding the use of code markers: a) Please consider whether you want the <CODE BEGINS> and <CODE ENDS> markers to be added to any snippets in this document (i.e., if you want to add markers="true" to the sourcecode elements). We note Section 3.2.1 contains the following, but how it should be applied within this document is not clear: 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). b) In contrast, regarding your note (about Section 3.7.1): * Added code markers for the security template. Why are the code markers being used for the security considerations template? It seems odd because it is prose, not code. c) Similarly, why are code markers used for the templates in Sections 4.30.3.1 and 4.30.3.2? --> <sourcecode name="" type="yang"><![CDATA[ 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; } }} ]]></sourcecode>}]]></sourcecode> <t>YANG defines the following rules for prefix usage:</t> <ul spacing="normal"> <li> <t>Prefixes are never used for built-in data types and YANG keywords.</t> </li> <li> <t>A prefix <bcp14>MUST</bcp14> be used for any external statement (i.e., a statement defined with the YANG "extension" statement).</t> </li> <li> <t>The proper module prefix <bcp14>MUST</bcp14> be used for all identifiers imported from other modules.</t> </li> <li> <t>The proper module prefix <bcp14>MUST</bcp14> be used for all identifiers included from a submodule.</t> </li> </ul> <t>The following guidelines apply to prefix usage of the current (local) module:</t> <ul spacing="normal"> <li> <t>The local module prefix <bcp14>SHOULD</bcp14> be used instead of no prefix in all path expressions.</t> </li> <li> <t>The local module prefix <bcp14>MUST</bcp14> be used instead of no prefix in all "default" statements for an "identityref" or "instance-identifier" data type.</t> </li> <li> <t>The local module prefix <bcp14>MAY</bcp14> be used for references to typedefs, groupings, extensions, features, and identities defined in the module.</t> </li> </ul> <t>Consistent with <xref section="7.1.4" sectionFormat="of" target="RFC7950"/>, the prefix defined by a module <bcp14>SHOULD</bcp14> be used when the module is imported, unless there is a conflict.</t> <t>Prefix values <bcp14>SHOULD</bcp14> be short but meaningful to the intended user. Prefix values <bcp14>SHOULD NOT</bcp14> conflict with known modules that have been previously published.</t> <t>For convenience, prefix values of example modules <bcp14>SHOULD</bcp14> be prefixed with "ex" or similar patterns. In doing so, readers of example modules or tree diagrams that mix both example and standard modules can easily identify example parts.</t> </section> <sectionanchor="identifiers">anchor="ids"> <name>Identifiers</name> <t>All YANG identifiers in published modules <bcp14>MUST</bcp14> be between 1 and 64 characters in length. These include any construct specified as an "identifier-arg-str" token in the ABNF in <xref section="14" sectionFormat="of" target="RFC7950"/>.</t> <section anchor="sec-id-naming"> <name>Identifier Naming Conventions</name> <t>Identifiers <bcp14>SHOULD</bcp14> follow a consistent naming pattern throughout the module. Only lowercase letters, numbers, and dashes <bcp14>SHOULD</bcp14> be used in identifier names. Uppercase characters, the period character, and the underscore character <bcp14>MAY</bcp14> be used if the identifier represents a well-known value that uses these characters. YANG does not permit any other characters in YANG identifiers.</t> <t>Identifiers <bcp14>SHOULD</bcp14> include complete words and/or well-known acronyms or abbreviations. Child nodes within a container or list <bcp14>SHOULD NOT</bcp14> 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.</t> <t>List identifiers <bcp14>SHOULD</bcp14> be singular with the surrounding container name plural. Similarly, "leaf-list" identifiers <bcp14>SHOULD</bcp14> be singular.</t> <t>It is permissible to use common identifiers such as "name" or "id" in data definition statements, especially if these data nodes share a common data type.</t> <t>Identifiers <bcp14>SHOULD NOT</bcp14> 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 is configuration data or state data. Only defined YANG statements or YANG extension statements can be used to assign semantics in a machine-readable format in YANG.</t> </section> </section> <section anchor="defaults"> <name>Defaults</name> <t>In general, it is suggested that substatements containing very common default values <bcp14>SHOULD NOT</bcp14> be present. The substatements listed in <xref target="stat-def"/> are commonly used with the default value, which would make the module difficult to read if used everywhere they are allowed.</t> <table anchor="stat-def"> <name>Statement Defaults</name> <thead> <tr> <th align="left">Statement</th> <th align="left">Default Value</th> </tr> </thead> <tbody> <tr> <td align="left">config</td> <td align="left">true</td> </tr> <tr> <td align="left">mandatory</td> <td align="left">false</td> </tr> <tr> <td align="left">max-elements</td> <td align="left">unbounded</td> </tr> <tr> <td align="left">min-elements</td> <td align="left">0</td> </tr> <tr> <td align="left">ordered-by</td> <td align="left">system</td> </tr> <tr> <td align="left">status</td> <td align="left">current</td> </tr> <tr> <td align="left">yin-element</td> <td align="left">false</td> </tr> </tbody> </table> </section> <section anchor="conditional-statements"> <name>Conditional Statements</name> <t>A module may be conceptually partitioned in severalways,ways using the "if-feature" and/or "when" statements.</t> <t>Data model designers need to carefully consider all modularity aspects, including the use of YANG conditional statements.</t> <t>If a data definition is optional, depending on server support for a NETCONF or RESTCONF protocol capability, then a YANG "feature" statement <bcp14>SHOULD</bcp14> be defined. The defined "feature" statement <bcp14>SHOULD</bcp14> then be used in the conditional "if-feature" statement referencing the optional data definition.</t> <t>If any notification data, or any data definition, for a non- configuration data node is not mandatory, then the server may or may not be required to return an instance of this data node. If any conditional requirements exist for returning the data node in a notification payload or retrieval request, they <bcp14>MUST</bcp14> be documented somewhere. For example, a "when" or "if-feature" statement could apply to the datanode,node or the conditional requirements could be explained in a "description" statement within the data node or one of its ancestors (if any).</t> <t>If any "if-feature" statements apply to a list node, then the same "if-feature" statements <bcp14>MUST</bcp14> apply to any key leaf nodes for the list. There <bcp14>MUST NOT</bcp14> be any "if-feature" statements applied to any key leafs that do not also apply to the parent list node.</t> <t>There <bcp14>SHOULD NOT</bcp14> be any "when" statements applied to a key leaf node. It is possible that a "when" statement for an ancestor node of a key leaf will have the exact node-set result as the key leaf. In such a case, the "when" statement for the key leaf is redundant and <bcp14>SHOULD</bcp14> be avoided.</t> <t>Some modules use a "case + when" construct but provide duplicated information (e.g., the "when" statements are constraining a single case in the choice as shown in the example below). Such constructs with duplicated information <bcp14>SHOULD NOT</bcp14> be used.</t> <sourcecode name="" type="yang"><![CDATA[ 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; } } }} ]]></sourcecode>}]]></sourcecode> <t>The following example removes the duplicated information:</t> <sourcecode name="" type="yang"><![CDATA[ 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; }} ]]></sourcecode>}]]></sourcecode> <t>Note that the use of "case + when" is still useful in cases where complementarymodellingmodeling constraints should be expressed. See the example providedbelow.</t>below:</t> <sourcecode name="" type="yang"><![CDATA[ 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; } } }} ]]></sourcecode>}]]></sourcecode> <t><xref section="8.1" sectionFormat="of" target="RFC7950"/> includes provisions for defining constraints on state data and specifies that a constraint must be true in a valid state data tree. However, <xref section="5.3" sectionFormat="of" target="RFC8342"/> softens that behavior by allowing semantic constraints to be violated under some circumstances to help to detect anomalies. Relaxing validation constraints on state data is meant to reveal deviations of the observed behaviorvs.versus intended behavior of a managed entity and hopefully trigger corrective actions by a management system. From that perspective, it is <bcp14>RECOMMENDED</bcp14> to avoid defining constraints on state data that would hinder the detection by a management system of abnormal behaviors of a managed entity.</t> </section> <section anchor="xpath-usage"> <name>XPath Usage</name> <t>This section describes guidelines for using the XML Path Language (XPath) <xref target="W3C.REC-xpath"/> within YANG modules.</t> <section anchor="xpath-evaluation-contexts"> <name>XPath Evaluation Contexts</name> <t>YANG defines five separate contexts for evaluation of XPath statements:</t> <ol spacing="normal" type="1"><li> <t>The "running" datastore: collection of all YANG configuration data nodes. The document root is the conceptual container (e.g., "config" in the "edit-config" operation), which is the parent of all top-level data definition statements with a "config" statement value of "true".</t> </li> <li> <t>State data + the "running" datastore: collection of all YANG data nodes. The document root is the conceptual container, parent of all top-level data definition statements.</t> </li> <li> <t>Notification: an event notification document. The document root is the notification element.</t> </li> <li> <t>RPC Input: The document root is the conceptual "input" node, which is the parent of all RPC input parameter definitions.</t> </li> <li> <t>RPC Output: The document root is the conceptual "output" node, which is the parent of all RPC output parameter definitions.</t> </li> </ol> <t>Note that these XPath contexts cannot be mixed. For example, a "when" statement in a notification context cannot reference configuration data.</t> <sourcecode name="" type="yang"><![CDATA[ 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"; } }} ]]></sourcecode>}]]></sourcecode> <t>It is especially important to consider the XPath evaluation context for XPath expressions defined in groupings. An XPath expression defined in a grouping may not be portable, meaning it cannot be used in multiple contexts and produce proper results.</t> <t>If the XPath expressions defined in a grouping are intended for a particular context, then this context <bcp14>SHOULD</bcp14> be identified in the "description" statement for the grouping.</t> </section> <section anchor="function-library"> <name>Function Library</name> <t>The "position" and "last" functions <bcp14>SHOULD NOT</bcp14> be used. This applies to implicit use of the "position" function as well (e.g., <tt>'//chapter[42]'</tt>). 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 <bcp14>MAY</bcp14> be used if they are evaluated in a context where the context node is a user- ordered "list" or "leaf-list".</t> <t>The "id" function <bcp14>SHOULD NOT</bcp14> be used. The "ID" attribute is not present in YANG documents, so this function has no meaning. The XPath execution environment <bcp14>SHOULD</bcp14> return an empty string for this function.</t> <t>The "namespace-uri" and "name" functions <bcp14>SHOULD NOT</bcp14> be used. Expanded names in XPath are different than YANG. A specific canonical representation of a YANG-expanded name does not exist.</t> <t>The "lang" function <bcp14>SHOULD NOT</bcp14> be used. This function does not apply to YANG because there is no "lang" attribute set with the document. The XPath execution environment <bcp14>SHOULD</bcp14> return "false" for this function.</t> <t>The "local-name", "namespace-uri", "name", "string", and "number" functions <bcp14>SHOULD NOT</bcp14> 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.</t> <t>The "local-name" function <bcp14>SHOULD NOT</bcp14> be used to reference local names outside of the YANG module that defines the must or when expression containing the "local-name" function. Example of a "local-name" function that should not be used:</t> <sourcecode name="" type="yang"><![CDATA[/*[local-name()='foo'] ]]></sourcecode>/*[local-name()='foo']]]></sourcecode> <t>The "derived-from-or-self" function <bcp14>SHOULD</bcp14> be used instead of an equality expression for identityref values. This allows the identities to be conceptually augmented.</t> <t>Example:</t> <sourcecode name="" type="yang"><![CDATA[ // 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')"; ]]></sourcecode>'ex:name-format-null')";]]></sourcecode> </section> <section anchor="axes"> <name>Axes</name> <t>The "attribute" and "namespace" axes are not supported in YANG and <bcp14>MAY</bcp14> be empty in a NETCONF or RESTCONF server implementation.</t> <t>The "preceding" and "following" axes <bcp14>SHOULD NOT</bcp14> 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) <bcp14>SHOULD</bcp14> be used instead. The "preceding" and "following" axes <bcp14>MAY</bcp14> be used if document order is not relevant to the outcome of the expression (e.g., check for global uniqueness of a parameter value).</t> <t>The "preceding-sibling" and "following-sibling" axes <bcp14>SHOULD NOT</bcp14> be used; however, they <bcp14>MAY</bcp14> be used if document order is not relevant to the outcome of the expression.</t> <t>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 <bcp14>MAY</bcp14> be used if they are evaluated in a context where the context node is a user-ordered "list" or "leaf-list".</t> </section> <section anchor="types"> <name>Types</name> <t>Data nodes that use the "int64" and "uint64" built-in type <bcp14>SHOULD NOT</bcp14> be used within numeric or boolean expressions. There are boundary conditions in which the translation from the YANG 64-bit type to an XPath number can cause incorrect results. Specifically, an XPath "double" precision floating-point number cannot represent very large positive or negative 64-bit numbers because it only provides a total precision of 53 bits. The "int64" and "uint64" data types <bcp14>MAY</bcp14> be used in numeric expressions if the value can be represented with no more than 53 bits of precision.</t> <t>Data modelers need to be careful not to confuse the YANG value space and the XPath value space. The data types are not the same in both, and conversion between YANG and XPath data types <bcp14>SHOULD</bcp14> be considered carefully.</t> <t>Explicit XPath data type conversions <bcp14>MAY</bcp14> be used (e.g., "string", "boolean", or "number" functions), instead of implicit XPath data type conversions.</t> <t>XPath expressions that contain a literal value representing a YANG identity <bcp14>SHOULD</bcp14> always include the declared prefix of the module where the identity is defined.</t> <t>XPath expressions for "when" statements <bcp14>SHOULD NOT</bcp14> reference the context node or any descendant nodes of the context node. They <bcp14>MAY</bcp14> reference descendant nodes if the "when" statement is contained within an "augment"statement,statement and the referenced nodes are not defined within the "augment" statement.</t> <t>Example:</t> <sourcecode name="" type="yang"><![CDATA[ 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} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="wildcards"> <name>Wildcards</name> <t>It is possible to construct XPath expressions that will evaluate differently when combined with several modules within a server implementation rather than when evaluated within the single module. This is due to augmenting nodes from other modules.</t> <t>Wildcard expansion is done within a server against all the nodes from all namespaces, so it is possible for a "must" or "when" expression that uses the <tt>'*'</tt> operator to always evaluate to false if processed within a single YANG module. In such cases, the "description" statement <bcp14>SHOULD</bcp14> clarify that augmenting objects are expected to match the wildcard expansion.</t> <sourcecode name="" type="yang"><![CDATA[ when /foo/services/*/active { description "No services directly defined in this module. Matches objects that have augmented the services container.";} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="boolean-expressions"> <name>Boolean Expressions</name> <t>The YANG "must" and "when" statements use an XPath boolean expression to define the test condition for the statement. It is important to specify these expressions in a way that will not cause inadvertent changes in the result if the objects referenced in the expression are updated in future revisions of the module.</t> <t>For example, the leaf "foo2" must exist if the leaf "foo1" is equal to "one" or "three":</t> <sourcecode name="" type="yang"><![CDATA[ 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;} ]]></sourcecode>}]]></sourcecode> <t>In the next revision of the module, leaf "foo1" is extended with a new enum named "four":</t> <sourcecode name="" type="yang"><![CDATA[ leaf foo1 { type enumeration { enum one; enum two; enum three; enum four; }} ]]></sourcecode>}]]></sourcecode> <t>Now the first XPath expression will allow the enum "four" to be accepted in addition to the "one" and "three" enum values.</t> </section> </section> <section anchor="yang-definition-lifecycle-management"> <name>YANG Definition Lifecycle Management</name> <t>The YANG status statement <bcp14>MUST</bcp14> be present within a definition if its value is "deprecated" or "obsolete". The status <bcp14>SHOULD NOT</bcp14> be changed from "current" directly to "obsolete". An object <bcp14>SHOULD</bcp14> be available for at least one year after the publication date with a "deprecated" status before it is changed to "obsolete".</t> <t>The module or submodule name <bcp14>MUST NOT</bcp14> bechanged,changed once the document containing the module or submodule is published.</t> <t>The module namespace URI value <bcp14>MUST NOT</bcp14> bechanged,changed once the document containing the module is published.</t> <t>The revision date substatement within the import statement <bcp14>SHOULD</bcp14> be present if any groupings are used from the external module.</t> <t>The revision date substatement within the include statement <bcp14>SHOULD</bcp14> be present if any groupings are used from the external submodule.</t> <t>If an import statement is for a module from a stable source (e.g., an RFC for an IETF module), then a reference-stmt <bcp14>SHOULD</bcp14> be present within an import statement.</t> <sourcecode name="" type="yang"><![CDATA[ import ietf-yang-types { prefix yang; reference "RFC 6991: Common YANG Data Types";} ]]></sourcecode>}]]></sourcecode> <t>If submodules are used, then the document containing the main module <bcp14>MUST</bcp14> be updated so that the main module revision date is equal to or more recent than the revision date of any submodule that is (directly or indirectly) included by the main module.</t> <t>Definitions for future use <bcp14>SHOULD NOT</bcp14> be specified in a module. Do not specify placeholder objects like the "reserved" example below:</t> <sourcecode name="" type="yang"><![CDATA[ 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.";} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="module-header-meta-and-revision-statements"> <name>Module Header, Meta, and Revision Statements</name> <t>For published modules, the namespace <bcp14>MUST</bcp14> be a globally unique URI, as defined in <xref target="RFC3986"/>. This value is usually assigned by the IANA.</t> <t>The "organization" statement <bcp14>MUST</bcp14> be present. If the module is contained in a document intended for IETF Standards Track status, then the organization <bcp14>SHOULD</bcp14> be the IETF working group (WG) chartered to write the document. Exceptions include (but are notlimited):limited to): example modules, IANA-maintained modules, or modules contained in AD-sponsored documents. For other standards organizations, a similar approach is also suggested.</t> <t>The "contact" statement <bcp14>MUST</bcp14> be present. If the module is contained in a document intended for Standards Track status, then the WG web and mailing information <bcp14>SHOULD</bcp14> be present, and the main document author or editor contact information <bcp14>SHOULD</bcp14> be present. If additional authors or editors exist, their contact information <bcp14>MAY</bcp14> be present. There is no need to include the contact information for WG Chairs.</t> <!--[rfced] Please review our update to the following text to clarify the punctuation and use of the BCP 14 keyword. Original: For modules published within IETF documents, the appropriate IETF Trust Copyright text MUST be present, as described in Section 3.1 and contain the following statement: Current: For modules published within IETF documents, the appropriate IETF Trust Copyright text MUST be present, as described in Section 3.1, and MUST contain the following statement: --> <t>The "description" statement <bcp14>MUST</bcp14> be present. For modules published within IETF documents, the appropriate IETF Trust Copyright text <bcp14>MUST</bcp14> be present, as described inSection 3.1<xref target="module-copyright"/>, and <bcp14>MUST</bcp14> contain the following statement:</t><ul empty="true"> <li> <t>All<blockquote><t>All revisions of IETF and IANA published modules can be found at the "YANG Parameters" registry group:https://www.iana.org/assignments/yang-parameters.</t> </li> </ul><eref target="https://www.iana.org/assignments/yang-parameters" brackets="angle"/>.</t></blockquote> <t>If the module relies on information contained in other documents, which are not the same documents implied by the import statements present in the module, then these documents <bcp14>MUST</bcp14> be identified in the reference statement.</t> <t>A "revision" statement <bcp14>MUST</bcp14> be present for each published version of the module. The "revision" statement <bcp14>MUST</bcp14> have a "reference" substatement. It <bcp14>MUST</bcp14> identify the published document that contains the module. Modules are often extracted from their original documents, and it is useful for developers and operators to know how to find the original source document in a consistent manner. The "revision" statement <bcp14>MAY</bcp14> have a "description" substatement. For convenience, the description text of a new published revision may summarize any changes made to a module compared to the previous published revision. Typically, that list is a YANG-specific subset of the summary of changes listing any changes made from the RFC being updated or obsoleted as per <xref target="ID-Guidelines"/>.</t> <t>The following example shows the revision statement for a published YANG module:</t> <sourcecode name="" type="yang"><![CDATA[ revision 2010-09-24 { description "Initial revision."; reference "RFC 6021: Common YANG Data Types";} ]]></sourcecode>}]]></sourcecode> <!--[rfced] We note that RFC 6021 and RFC 6991 have been obsoleted by RFC 9911. Please review mentions in the text and let us know how you would like to update. --> <t>The following example shows the revision statements for a published YANG module that updates a published module. The new revision statement summarizes the changes compared to the previous published revision.</t> <sourcecode name="" type="yang"><![CDATA[ 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";} ]]></sourcecode>}]]></sourcecode> <t>For an unpublished module, a complete history of each unpublished module revision is not required. That is, within a sequence of draft versions, only the most recent revision need be recorded in the module. Do not remove or reuse a revision statement for a published module. A new revision date is not required unless the module contents have changed. If the module contents have changed, then the revision date of that new module version <bcp14>MUST</bcp14> be updated to a date later than that of the previous version.</t> <t>The following example shows the revision statements for an unpublished update to a published YANG module. The latest revision statement of the unpublished module summarizes the changes compared to the previous revision.</t> <sourcecode name="" type="yang"><![CDATA[ revision 2023-01-23 { description "This revision adds the following new data types: - yang:date-with-zone-offset - yang:date-no-zone - yang:time-with-zone-offset - 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. Several pattern statements have been improved."; reference "RFCYYYY:6991: 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";} ]]></sourcecode>}]]></sourcecode> </section> <!--[rfced] Would you like to add examples of "reference" substatements? The RPC and OPS ADs discussed this topic during IETF 123. The examples would show that the RFC title does not need to be included. (The exception is in the "revision" statement, where the title is typically included.) For example: reference (with section) "RFC 8665, Section 5 RFC 8666, Section 6"; reference (just RFC number) "RFC 8665 RFC 8666"; --> <section anchor="sec-namespace-assignments"> <name>Namespace Assignments</name> <t>It is <bcp14>RECOMMENDED</bcp14> that only valid YANG modules be included in documents, whether or not the modules are published yet. This allows:</t> <ul spacing="normal"> <li> <t>the module to compile correctly instead of generating disruptive fatal errors.</t> </li> <li> <t>early implementors to use the modules without picking a random value for the XML namespace.</t> </li> <li> <t>early interoperability testing since independent implementations will use the same XML namespace value.</t> </li> </ul> <t>Until a URI is assigned by the IANA, a proposed namespace URI <bcp14>MUST</bcp14> be provided for the namespace statement in a YANG module. A value <bcp14>SHOULD</bcp14> be selected that is not likely to collide with other YANG namespaces. Standard module names, prefixes, and URI strings already listed in the "YANG Module Names" registry group <bcp14>MUST NOT</bcp14> be used.</t> <t>A standard namespace statement value <bcp14>SHOULD</bcp14> have the following form:</t><artwork><![CDATA[<sourcecode type="pseudocode"><![CDATA[ <URN prefixstring>:<module-name> ]]></artwork>string>:<module-name>]]></sourcecode> <t>The following URN prefix string <bcp14>SHOULD</bcp14> be used for published and unpublished YANG modules:</t><artwork><![CDATA[ urn:ietf:params:xml:ns:yang ]]></artwork><sourcecode type="pseudocode"><![CDATA[ urn:ietf:params:xml:ns:yang]]></sourcecode> <t>The following example URNs would be valid namespace statement values for Standards Track modules:</t><artwork><![CDATA[ urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock urn:ietf:params:xml:ns:yang:ietf-netconf-state urn:ietf:params:xml:ns:yang:ietf-netconf ]]></artwork><sourcecode type="pseudocode"><![CDATA[ urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock]]></sourcecode> <sourcecode type="pseudocode"><![CDATA[ urn:ietf:params:xml:ns:yang:ietf-netconf-state]]></sourcecode> <sourcecode type="pseudocode"><![CDATA[ urn:ietf:params:xml:ns:yang:ietf-netconf]]></sourcecode> <t>Note that a different URN prefix string <bcp14>SHOULD</bcp14> be used for modules that are not Standards Track. The string <bcp14>SHOULD</bcp14> be selected according to the guidelines in <xref section="5.3" sectionFormat="of" target="RFC7950"/>.</t> <t>The following URIs exemplify what might be used by modules that are not Standards Track. Note that the domain "example.com" <bcp14>SHOULD</bcp14> be used by example modules in I-Ds from the IETFI-Ds.Stream. These URIs are not intended to be dereferenced. They are used for module namespace identification only.</t> <t>Example URIs using URLs per <xref target="RFC3986"/>:</t><artwork><![CDATA[ https://example.com/ns/example-interfaces https://example.com/ns/example-system ]]></artwork><sourcecode type="pseudocode"><![CDATA[ https://example.com/ns/example-interfaces]]></sourcecode> <sourcecode type="pseudocode"><![CDATA[ https://example.com/ns/example-system]]></sourcecode> <t>Example URIs using tags per <xref target="RFC4151"/>:</t><artwork><![CDATA[ tag:example.com,2017:example-interfaces tag:example.com,2017:example-system ]]></artwork><sourcecode type="pseudocode"><![CDATA[ tag:example.com,2017:example-interfaces]]></sourcecode> <sourcecode type="pseudocode"><![CDATA[ tag:example.com,2017:example-system]]></sourcecode> </section> <section anchor="top-level-data-definitions"> <name>Top-Level Data Definitions</name> <t>The top-level data organization <bcp14>SHOULD</bcp14> be considered carefully, in advance. Data model designers need to consider how the functionality for a given protocol or protocol family will grow over time.</t> <t>The separation of configuration data and operational state <bcp14>SHOULD</bcp14> be considered carefully. It is sometimes useful to define separate top- level containers for configuration and non-configuration data. For some existing top-level data nodes, configuration data was not in scope, so only one container representing operational state was created. Refer to NMDA <xref target="RFC8342"/> for details.</t> <t>The number of top-level data nodes within a module <bcp14>SHOULD</bcp14> be minimized. It is often useful to retrieve related information within a single subtree. If data is too distributed, it becomes difficult to retrieve all at once.</t> <t>The names and data organization <bcp14>SHOULD</bcp14> reflect persistent information, such as the name of a protocol. The name of the working group <bcp14>SHOULD NOT</bcp14> be used because this may change over time.</t> <t>A mandatory database data definition is defined as a node that a client must provide for the database to be valid. The server is not required to provide a value.</t> <t>Top-level database data definitions <bcp14>MUST NOT</bcp14> be mandatory. If a mandatory node appears at the top level, it will immediately cause the database to be invalid. This can occur when the server boots or when a module is loaded dynamically at runtime.</t> </section> <section anchor="data-types"> <name>Data Types</name> <t>Selection of an appropriate data type (i.e., built-in type, existing derived type, or new derived type) is very subjective; therefore, few requirements can be specified on that subject.</t> <t>Data model designers <bcp14>SHOULD</bcp14> use the most appropriate built-in data type for the particular application.</t> <t>The signed numeric data types (i.e., "int8", "int16", "int32", and "int64") <bcp14>SHOULD NOT</bcp14> be used unless negative values are allowed for the desired semantics.</t> <section anchor="sec-fve"> <name>Fixed-Value Extensibility</name> <t>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 <bcp14>SHOULD</bcp14> be used.</t> <sourcecode name="" type="yang"><![CDATA[ leaf foo { type enumeration { enum one; enum two; }} ]]></sourcecode>}]]></sourcecode> <t>If distributed extensibility or hierarchical organization of enumerated values is required, then the "identityref" data type <bcp14>SHOULD</bcp14> be used instead of an enumeration or other built-in type.</t> <sourcecode name="" type="yang"><![CDATA[ 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; }} ]]></sourcecode>}]]></sourcecode> <t>Note that any module can declare an identity with base "foo-type" that is valid for the "foo" leaf. Identityref values are considered to be qualified names.</t> </section> <section anchor="patterns-and-ranges"> <name>Patterns and Ranges</name> <t>For string data types, if a machine-readable pattern can be defined for the desired semantics, then one or more pattern statements <bcp14>SHOULD</bcp14> be present. A single-quoted string <bcp14>SHOULD</bcp14> 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 <bcp14>SHOULD</bcp14> be documented within the typedef or data definition.</t> <t>The following typedef from <xref target="RFC6991"/> demonstrates the proper use of the "pattern" statement:</t> <sourcecode name="" type="yang"><![CDATA[ typedef ipv6-address-no-zone { type inet:ipv6-address { pattern '[0-9a-fA-F:\.]*'; } ...} ]]></sourcecode>}]]></sourcecode> <t>For string data types, if the length of the string is required to be bounded in all implementations, then a length statement <bcp14>MUST</bcp14> be present.</t> <t>The following typedef from <xref target="RFC6991"/> demonstrates the proper use of the "length" statement:</t> <sourcecode name="" type="yang"><![CDATA[ typedef yang-identifier { type string { length "1..max"; pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; } ...} ]]></sourcecode>}]]></sourcecode> <t>For numeric data types, if the values allowed by the intended semantics are different than those allowed by the unbounded intrinsic data type (e.g., "int32"), then a range statement <bcp14>SHOULD</bcp14> be present.</t> <t>The following typedef from <xref target="RFC6991"/> demonstrates the proper use of the "range" statement:</t> <sourcecode name="" type="yang"><![CDATA[ typedef dscp { type uint8 { range "0..63"; } ...} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="enumerations-and-bits"> <name>Enumerations and Bits</name> <t>For "enumeration" or "bits" data types, the semantics for each "enum" or "bit" <bcp14>SHOULD</bcp14> be documented. A separate "description" statement (within each "enum" or "bit" statement) <bcp14>SHOULD</bcp14> be present.</t> <sourcecode name="" type="yang"><![CDATA[ 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... ";} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="union-types"> <name>Union Types</name> <t>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 <bcp14>SHOULD</bcp14> be ordered from most restrictive to least restrictive types.</t> <t>In the following example, the "enumeration" type will never be matched because the preceding "string" type will match everything.</t> <t>Incorrect:</t> <sourcecode name="" type="yang"><![CDATA[ type union { type string; type enumeration { enum up; enum down; }} ]]></sourcecode>}]]></sourcecode> <t>Correct:</t> <sourcecode name="" type="yang"><![CDATA[ type union { type enumeration { enum up; enum down; } type string;} ]]></sourcecode>}]]></sourcecode> <t>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.</t> <t>In the following example, a JSON numeric value will always be matched by the "int32" type, but in XML the string value representing a number will be matched by the "string" type. The second version will match the "int32" member type no matter how the input is encoded.</t> <t>Incorrect:</t> <sourcecode name="" type="yang"><![CDATA[ type union { type string; type int32;} ]]></sourcecode>}]]></sourcecode> <t>Correct:</t> <sourcecode name="" type="yang"><![CDATA[ type union { type int32; type string;} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="empty-and-boolean"> <name>Empty and Boolean</name> <t>YANG provides an "empty" data type, which has one value (i.e., present). The default is "not present", which is not actually a value. When used within a list key, only one value can (and must) exist for this key leaf. The type "empty" <bcp14>SHOULD NOT</bcp14> be used for a key leaf since it is pointless.</t> <t>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" <bcp14>SHOULD NOT</bcp14> be used for a leaf-list.</t> <t>The advantage of using type "empty" instead of type "boolean" is that the default (not present) does not take up any bytes in a representation. The disadvantage is that the client may not be sure if an empty leaf is missing because it was filtered somehow or not implemented. The client may not have a complete and accurate schema for the data returned by the server and may not be aware of the missing leaf.</t> <t>The YANG "boolean" data type provides two values ("true" and "false"). When used within a list key, two entries can exist for this key leaf. Default values are ignored for key leafs, but a default statement is often used for plain boolean leafs. The advantage of the "boolean" type is that the leaf or leaf-list has a clear representation for both values. The default value is usually not returned unless explicitly requested by the client, so no bytes are used in a typical representation.</t> <t>In general, the "boolean" data type <bcp14>SHOULD</bcp14> be used instead of the "empty" data type, as shown in the example below:</t> <t>Incorrect:</t> <sourcecode name="" type="yang"><![CDATA[ leaf flag1 { type empty;} ]]></sourcecode>}]]></sourcecode> <t>Correct:</t> <sourcecode name="" type="yang"><![CDATA[ leaf flag2 { type boolean; default false;} ]]></sourcecode>}]]></sourcecode> </section> </section> <section anchor="reusable-type-definitions"> <name>Reusable Type Definitions</name> <t>If an appropriate derived type exists in any standard module, such as <xref target="RFC6991"/>, then it <bcp14>SHOULD</bcp14> be used instead of defining a new derived type.</t> <t>If an appropriate units identifier can be associated with the desired semantics, then a units statement <bcp14>SHOULD</bcp14> be present.</t> <t>If an appropriate default value can be associated with the desired semantics, then a default statement <bcp14>SHOULD</bcp14> be present.</t> <t>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 <bcp14>SHOULD</bcp14> be contained in a separate module orsubmodule,submodule to allow easier reuse without unnecessary coupling.</t> <t>The "description" statement <bcp14>MUST</bcp14> be present.</t> <t>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 <bcp14>MUST</bcp14> be present.</t> </section> <section anchor="reusable-groupings"> <name>Reusable Groupings</name> <t>A reusable grouping is a YANG grouping that can be imported by another module and is intended for use by other modules. This is not the same as a grouping that is used within the module in which it is defined, but it happens to be exportable to another module because it is defined at the top level of the YANG module.</t> <t>The following guidelines apply to reusable groupings, in order to make them as robust as possible:</t> <ul spacing="normal"> <li> <t>Clearly identify the purpose of the grouping in the "description" statement.</t> </li> <li> <t>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.</t> </li> <li> <t>Do not reference data outside the grouping in any "path", "must", or "when" statements.</t> </li> <li> <t>Do not include a "default" substatement on a leaf or choice unless the value applies on all possible contexts.</t> </li> <li> <t>Do not include a "config" substatement on a data node unless the value applies on all possible contexts.</t> </li> <li> <t>Clearly identify any external dependencies in the grouping "description" statement, such as nodes referenced by an absolute path from a "path", "must", or "when" statement.</t> </li> </ul> </section> <section anchor="sec-data-def"> <name>Data Definitions</name> <t>The "description" statement <bcp14>MUST</bcp14> be present in the following YANG statements:</t> <ul spacing="normal"> <li> <t>anydata</t> </li> <li> <t>anyxml</t> </li> <li> <t>augment</t> </li> <li> <t>choice</t> </li> <li> <t>container</t> </li> <li> <t>extension</t> </li> <li> <t>feature</t> </li> <li> <t>grouping</t> </li> <li> <t>identity</t> </li> <li> <t>leaf</t> </li> <li> <t>leaf-list</t> </li> <li> <t>list</t> </li> <li> <t>notification</t> </li> <li> <t>rpc</t> </li> <li> <t>typedef</t> </li> </ul> <t>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 <bcp14>MUST</bcp14> be present.</t> <t>The "anyxml" construct may be useful to represent an HTML banner containing markup elements, such as <tt>"<b>" and "</b>"</tt>, and <bcp14>MAY</bcp14> be used in such cases. However, this construct <bcp14>SHOULD NOT</bcp14> be used if other YANG data node types can be used instead to represent the desired syntax and semantics.</t> <t>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.</t> <t>If there are referential integrity constraints associated with the desired semantics that can be represented with XPath, then one or more "must" statements <bcp14>SHOULD</bcp14> be present.</t> <t>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 <bcp14>SHOULD</bcp14> be present.</t> <t>If any "must" or "when" statements are used within the data definition, then the data definition "description" statement <bcp14>SHOULD</bcp14> describe the purpose of each one.</t> <t>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.</t> <t>If a list defines any key leafs, then these leafs <bcp14>SHOULD</bcp14> be defined in order, as the first child nodes within the list. The key leafs <bcp14>MAY</bcp14> be in a different order in some cases, e.g., they are defined in a grouping, and not inline in the list statement.</t> <section anchor="non-presence-containers"> <name>Non-Presence Containers</name> <t>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).</t> <t>Example using container wrappers:</t> <sourcecode name="" type="yang"><![CDATA[ container top { container foos { list foo { ... } } container bars { list bar { ... } }} ]]></sourcecode>}]]></sourcecode> <t>Example without container wrappers:</t><artwork><![CDATA[<sourcecode name="" type="yang"><![CDATA[ container top { list foo { ... } list bar { ... }} ]]></artwork>}]]></sourcecode> <t>Use of non-presence containers to organize data is a subjective matter similar to use of subdirectories in a file system. Although these containers do not have any semantics, they can impact protocol operations for the descendant data nodes within a non-presence container, so use of these containers <bcp14>SHOULD</bcp14> be considered carefully.</t> <t>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).</t> </section> <section anchor="top-level-data-nodes"> <name>Top-Level Data Nodes</name> <t>Use of top-level objects needs to be considered carefully:</t> <ul spacing="normal"> <li> <t>top-level siblings are not ordered</t> </li> <li> <t>top-level siblings are not static and depend on the modules that are loaded</t> </li> <li> <t>for subtree filtering, retrieval of a top-level leaf-list will be treated as a content-match node for all top-level-siblings</t> </li> <li> <t>a top-level list with many instances may impact performance</t> </li> </ul> </section> </section> <section anchor="operation-definitions"> <name>Operation Definitions</name> <t>If the operation semantics are defined in an external document (other than another YANG module indicated by an import statement), then a reference statement <bcp14>MUST</bcp14> be present.</t> <t>If the operation impacts system behavior in some way, it <bcp14>SHOULD</bcp14> be mentioned in the "description" statement.</t> <t>If the operation is potentially harmful to system behavior in some way, it <bcp14>MUST</bcp14> be mentioned in the Security Considerations section of the document.</t> </section> <section anchor="notification-definitions"> <name>Notification Definitions</name> <t>The "description" statement <bcp14>MUST</bcp14> be present.</t> <t>If the notification semantics are defined in an external document (other than another YANG module indicated by an import statement), then a reference statement <bcp14>MUST</bcp14> be present.</t> <t>If the notification refers to a specific resource instance, then this instance <bcp14>SHOULD</bcp14> 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:</t> <sourcecode name="" type="yang"><![CDATA[ notification interface-up { description "Sent when an interface is activated."; leaf name { type leafref { path "/if:interfaces/if:interface/if:name"; } }} ]]></sourcecode>}]]></sourcecode> <t>Note that there are no formal YANG statements to identify any data node resources associated with a notification. The "description" statement for the notification <bcp14>SHOULD</bcp14> specify if and how the notification identifies any data node resources associated with the specific event.</t> </section> <section anchor="feature-definitions"> <name>Feature Definitions</name> <t>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 <bcp14>MUST</bcp14> specify any interactions with other features.</t> <t>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.</t> <t>If there is a large set of objects associated with a YANG feature, then consider moving those objects to a separatemodule,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.</t> <t>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.</t> <t>If one feature requires implementation of another feature, then an "if-feature" statement <bcp14>SHOULD</bcp14> be used in the dependent "feature" statement.</t> <t>For example, feature2 requires implementation of feature1:</t> <sourcecode name="" type="yang"><![CDATA[ feature feature1 { description "Some protocol feature"; } feature feature2 { if-feature "feature1"; description "Another protocol feature";} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="yang-data-node-constraints"> <name>YANG Data Node Constraints</name> <section anchor="controlling-quantity"> <name>Controlling Quantity</name> <t>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 <bcp14>SHOULD</bcp14> 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) <bcp14>SHOULD</bcp14> be used to identify the limit.</t> </section> <section anchor="must-versus-when"> <name>"must" versus "when"</name> <t>"must" and "when" YANG statements are used to provide cross-object referential tests. They have very different behavior. The "when" statement causes data node instances to be silently deleted as soon as the condition becomes false. A false "when" expression is not considered to be an error.</t> <t>The "when" statement <bcp14>SHOULD</bcp14> be used together with "augment" or "uses" statements to achieve conditional model composition. The condition <bcp14>SHOULD</bcp14> be based on static properties of the augmented entry (e.g., list key leafs).</t> <t>The "must" statement causes a datastore validation error if the condition is false. This statement <bcp14>SHOULD</bcp14> 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).</t> </section> </section> <section anchor="augment-statements"> <name>"augment" Statements</name> <t>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.</t> <t>A top-level "augment" statement <bcp14>SHOULD NOT</bcp14> be used if the target data node is in the same module or submodule as the evaluated "augment" statement. The data definition statements <bcp14>SHOULD</bcp14> be added inline instead.</t> <section anchor="conditional-augment-statements"> <name>Conditional Augment Statements</name> <t>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.</t> <t>The following example from <xref target="RFC8343"/> shows how a conditional container called "ethernet" is added to the "interface" list only for entries of the type "ethernetCsmacd".</t> <sourcecode name="" type="yang"><![CDATA[ augment "/if:interfaces/if:interface" { when "if:type = 'ianaift:ethernetCsmacd'"; container ethernet { leaf duplex { ... } }} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="conditionally-mandatory-data-definition-statements"> <name>Conditionally Mandatory Data Definition Statements</name> <t>YANG has very specific rules about how configuration data can be updated in new releases of a module. These rules allow an "old client" to continue interoperating with a "new server".</t> <t>If data nodes are added to an existing entry, the old client <bcp14>MUST NOT</bcp14> be required to provide any mandatory parameters that were not in the original module definition.</t> <t>It is possible to add conditional "augment" statements such that the old client would not know about the new condition and would not specify the new condition. The conditional "augment" statement can contain mandatory objects only if the condition is false, unless explicitly requested by the client.</t> <t>Only a conditional "augment" statement that uses the "when" statement form of a condition can be used in this manner. The YANG features enabled on the server cannot be controlled by the client in any way, so it is not safe to add mandatory augmenting data nodes based on the "if-feature" statement.</t> <t>The XPath "when" statement condition <bcp14>MUST NOT</bcp14> reference data outside of the target data node because the client does not have any control over this external data.</t> <t>In the following sample, it is okay to augment the "interface" entry with "mandatory-leaf" because the augmentation depends on support for "some-new-iftype". The old client does not know about this type, so it would never select this type; therefore, it would not add a mandatory data node.</t> <sourcecode name="" type="yang"><![CDATA[ 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; } }} ]]></sourcecode>}]]></sourcecode> <t>Note that this practice is safe only for creating data resources. It is not safe for replacing or modifying resources if the client does not know about the new condition. The YANG data model <bcp14>MUST</bcp14> be packaged in a way that requires the client to be aware of the mandatory data nodes if it is aware of the condition for this data. In the example above, the "some-new-iftype" identity is defined in the same module as the "mandatory-leaf" data definition statement.</t> <t>This practice is not safe for identities defined in a common module such as "iana-if-type" because the client is not required to know about "my-module" just because it knows about the "iana-if-type" module.</t> </section> </section> <section anchor="deviation-statements"> <name>Deviation Statements</name> <t>Per <xref section="7.20.3" sectionFormat="of" target="RFC7950"/>, the YANG "deviation" statement is not allowed to appear in IETF YANG modules, but it can be useful for documenting server capabilities. Deviation statements are not reusable and typically not shared across all platforms.</t> <t>There are several reasons that deviations might be needed in an implementation, e.g., an object cannot be supported on all platforms, or feature delivery is done in multiple development phases. Deviation statements can also be used to add annotations to a module, which does not affect the conformance requirements for the module.</t> <t>It is suggested that deviation statements be defined in separate modules from regular YANG definitions. This allows the deviations to be platform specific and/or temporary.</t> <t>The order that deviation statements are evaluated can affect the result. Therefore, multiple deviation statements in the same module, for the same target object, <bcp14>SHOULD NOT</bcp14> be used.</t> <t>The "max-elements" statement is intended to describe an architectural limit to the number of list entries. It is not intended to describe platform limitations. It is better to use a "deviation" statement for the platforms that have a hard resource limit.</t> <t>Example documenting platform resource limits:</t><sourcecode type="yang"><![CDATA[ Wrong:<t>Wrong: (max-elements in the listitself)itself)</t> <sourcecode name="" type="yang"><![CDATA[ container backups { list backup { ... max-elements 10; ... }} ]]></sourcecode> <sourcecode type="yang"><![CDATA[ Correct:}]]></sourcecode> <t>Correct: (max-elements in adeviation)deviation)</t> <sourcecode name="" type="yang"><![CDATA[ deviation /bk:backups/bk:backup { deviate add { max-elements 10; }} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="extension-statements"> <name>Extension Statements</name> <t>The YANG "extension" statement is used to specify external definitions. This appears in the YANG syntax as an "unknown-statement". Usage of extension statements in a published module needs to be considered carefully.</t> <t>The following guidelines apply to the usage of YANG extensions:</t> <ul spacing="normal"> <li> <t>The semantics of the extension <bcp14>MUST NOT</bcp14> contradict any YANG statements. Extensions can add semantics not covered by the normal YANG statements.</t> </li> <li> <t>The module containing the extension statement <bcp14>MUST</bcp14> clearly identify the conformance requirements for the extension. It should be clear whether all implementations of the YANG module containing the extension need to also implement the extension. If not, identify what conditions apply that would require implementation of the extension.</t> </li> <li> <t>The extension <bcp14>MUST</bcp14> clearly identify where it can be used within other YANG statements.</t> </li> <li> <t>The extension <bcp14>MUST</bcp14> clearly identify if YANG statements or other extensions are allowed or required within the extension as substatements.</t> </li> </ul> </section> <section anchor="data-correlation"> <name>Data Correlation</name> <t>Data can be correlated in various ways, using common data types, common data naming, and common data organization. There are several ways to extend the functionality of a module, based on the degree of coupling between the old and new functionality:</t> <dl> <dt>inline:</dt> <dd> <t>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.</t> </dd> <dt>augment:</dt> <dd> <t>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.</t> </dd> <dt>mirror:</dt> <dd> <t>create new objects in a new module or the original module, except use a new naming scheme and data location. The naming can be coupled in different ways. Tight coupling is achieved with a "leafref" data type, with the "require-instance" substatement set to "true". This method <bcp14>SHOULD</bcp14> be used.</t> </dd> </dl> <t>If the new data instances are not limited to the values in use in the original data structure, then the "require-instance" substatement <bcp14>MUST</bcp14> 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".</t> <t>The relationship between configuration and operational state has been clarified in NMDA <xref target="RFC8342"/>.</t> <section anchor="use-of-leafref-for-key-correlation"> <name>Use of "leafref" for Key Correlation</name> <t>Sometimes it is not practical to augment a data structure. For example, the correlated data could have different keys or contain mandatory nodes.</t> <t>The following example shows the use of the "leafref" data type for data correlation purposes:</t> <t>Not preferred:</t> <sourcecode name="" type="yang"><![CDATA[ list foo { key name; leaf name { type string; } ... } list foo-addon { key name; config false; leaf name { type string; } ...} ]]></sourcecode>}]]></sourcecode> <t>Preferred:</t> <sourcecode name="" type="yang"><![CDATA[ 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; }} ]]></sourcecode>}]]></sourcecode> </section> </section> <section anchor="sec-op-state"> <name>Operational State</name> <t>The modeling of operational state with YANG has been refined over time. At first, only data that has a "config" statement value of "false" was considered to be operational state. This data was not considered to be part of any datastore, which made the YANG XPath definition much more complicated.</t> <t>Operational state is now modeled using YANG according to the NMDA <xref target="RFC8342"/> and conceptually contained in the operational state datastore, which also includes the operational values of configuration data. There is no longer any need to duplicate data structures to provide separate configuration and operational state sections.</t> <t>This section describes some data modeling issues related to operational state and guidelines for transitioning YANG data model design to be NMDA compatible.</t> <section anchor="combining-operational-state-and-configuration-data"> <name>Combining Operational State and Configuration Data</name> <t>If possible, operational state <bcp14>SHOULD</bcp14> be combined with its associated configuration data. This prevents duplication of key leafs and ancestor nodes. It also prevents race conditions for retrieval of dynamic entries and allows configuration and operational state to be retrieved together with minimal message overhead.</t> <sourcecode name="" type="yang"><![CDATA[ container foo { ... // contains "config true" and "config false" nodes that have // no corresponding "config true" object (e.g., counters)} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="sec-4.23.2"> <name>Representing Operational Values of Configuration Data</name> <t>If possible, the same data type <bcp14>SHOULD</bcp14> be used to represent the configured value and the operational value, for a given leaf or leaf- list object.</t> <t>Sometimes the configured value set is different than the operational value set for that object, for example, the "admin-status" and "oper-status" leafs in <xref target="RFC8343"/>. In this case, a separate object <bcp14>MAY</bcp14> be used to represent the configured and operational values.</t> <t>Sometimes the list keys are not identical for configuration data and the corresponding operational state. In this case, separate lists <bcp14>MAY</bcp14> be used to represent the configured and operational values.</t> <t>If it is not possible to combine configuration and operational state, then the keys used to represent list entries <bcp14>SHOULD</bcp14> be the same type. The "leafref" data type <bcp14>SHOULD</bcp14> be used in operational state for key leafs that have corresponding configuration instances. The "require-instance" statement <bcp14>MAY</bcp14> be set to "false" (in YANG 1.1 modules only) to indicate instances are allowed in the operational state that do not exist in the associated configuration data.</t> <t>The need to replicate objects or define different operational state objects depends on the data model. It is not possible to define one approach that will be optimal for all data models.</t> <t>Designers <bcp14>SHOULD</bcp14> 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 <bcp14>SHOULD</bcp14> be used for this purpose.</t> </section> <section anchor="nmda-transition-guidelines"> <name>NMDA Transition Guidelines</name> <t>YANG modules <bcp14>SHOULD</bcp14> be designed with the assumption that they will be used on servers supporting the operational state datastore. With this in mind, YANG modules <bcp14>SHOULD</bcp14> define "config false" nodes wherever they make sense to the data model. "Config false" nodes <bcp14>SHOULD NOT</bcp14> be defined to provide the operational value for configuration nodes, except when the value space of a configured and operational value may differ, in which case a distinct "config false" node <bcp14>SHOULD</bcp14> be defined to hold the operational value for the configured node.</t> <t>The following guidelines are meant to help modelers develop YANG modules that will maximize the utility of the model with both current and new implementations.</t> <t>New modules and modules that are not concerned with the operational state of configuration information <bcp14>SHOULD</bcp14> immediately be structured to be NMDA compatible, as described inSection 4.23.1.<xref target="combining-operational-state-and-configuration-data"/>. This transition <bcp14>MAY</bcp14> be deferred if the module does not contain any configuration datastore objects.</t> <t>The remaining are options that <bcp14>MAY</bcp14> be followed during the time that NMDA mechanisms are being defined.</t> <ol group="bar" spacing="normal" type="(%c)"><li> <t>Modules that require immediate support for the NMDA features <bcp14>SHOULD</bcp14> be structured for NMDA. A temporary non-NMDA version of this type of module <bcp14>MAY</bcp14> exist, as either an existing model or a model created by hand or with suitable tools that mirror the current modeling strategies. Both the NMDA and the non-NMDA modules <bcp14>SHOULD</bcp14> be published in the same document, with NMDA modules in the document main body and the non-NMDA modules in a non-normative appendix. The use of the non-NMDA module will allow temporary bridging of the time period until NMDA implementations are available.</t> </li> <li> <t>For published models, the model should be republished with an NMDA-compatible structure, deprecating non-NMDA constructs. For example, the "ietf-interfaces" model in <xref target="RFC7223"/> has been restructured as an NMDA-compatible model in <xreftarget="RFC8343"/>.target="RFC8343"/> (which obsoletes <xref target="RFC7223"/>). The "/interfaces-state" hierarchy has been marked "status deprecated". Models that mark their "/foo-state" hierarchy with "status deprecated" will allow NMDA-capable implementations to avoid the cost of duplicating the state nodes, while enabling non-NMDA-capable implementations to utilize them for access to the operational values.</t> </li> <li> <t>For models that augment models that have not been structured with the NMDA, the modeler will have to consider the structure of the base model and the guidelines listed above. Where possible, such models should move to new revisions of the base model that are NMDA compatible. When that is not possible, augmenting "state" containers <bcp14>SHOULD</bcp14> be avoided, with the expectation that the base model will be re-released with the state containers marked as deprecated. It is <bcp14>RECOMMENDED</bcp14> to augment only the "/foo" hierarchy of the base model. Where this recommendation cannot be followed,thenany new "state" elements <bcp14>SHOULD</bcp14> be included in their own module.</t> </li> </ol> <section anchor="temporary-non-nmda-modules"> <name>Temporary Non-NMDA Modules</name> <t>A temporary non-NMDA module allows a non-NMDA-aware client to access operational state from an NMDA-compliant server. It contains the top-level "config false" data nodes that would have been defined in a legacy YANG module (before NMDA).</t> <t>A server that needs to support both NMDA and non-NMDA clients can advertise both the new NMDA module and the temporary non-NMDA module. A non-NMDA client can use separate "foo" and "foo-state" subtrees, except the "foo-state" subtree is located in a different (temporary) module. The NMDA module can be used by a non-NMDA client to access the conventional configuration datastores and the deprecated <tt><get></tt> operation to access nested "config false" data nodes.</t> <t>To create the temporary non-NMDA model from an NMDA model, the following steps can be taken:</t> <ul spacing="normal"> <li> <t>Change the module name by appending "-state" to the original modulename</t>name.</t> </li> <li> <t>Change the namespace by appending "-state" to the original namespacevalue</t>value.</t> </li> <li> <t>Change the prefix by appending "-s" to the original prefixvalue</t>value.</t> </li> <li> <t>Add an import to the original module (e.g., for typedefdefinitions)</t>definitions).</t> </li> <li> <t>Retain or create only the top-level nodes that have a "config" statement value "false". These subtrees represent "config false" data nodes that were combined into the configuration subtree; therefore, they are not available tonon-NMDA awarenon-NMDA-aware clients. Set the "status" statement to "deprecated" for each new node.</t> </li> <li> <t>The module description <bcp14>SHOULD</bcp14> clearly identify the module as a temporary non-NMDAmodule</t>module.</t> </li> </ul> </section> <section anchor="example-create-a-new-nmda-module"> <name>Example: Create a New NMDA Module</name> <t>Create an NMDA-compliant module, using combined configuration and state subtrees, whenever possible.</t> <sourcecode name="" type="yang"><![CDATA[ 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 }} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="example-convert-an-old-non-nmda-module"> <name>Example: Convert an Old Non-NMDA Module</name> <t>Do not remove non-compliant objects from existing modules. Instead, change the status to "deprecated". At some point, usually after 1 year, the status <bcp14>MAY</bcp14> be changed to "obsolete".</t> <t>Old Module:</t> <sourcecode name="" type="yang"><![CDATA[ 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 }} ]]></sourcecode> <artwork><![CDATA[ Converted}]]></sourcecode> <t>Converted NMDAModule: ]]></artwork>Module:</t> <sourcecode name="" type="yang"><![CDATA[ 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 }} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="example-create-a-temporary-nmda-module"> <name>Example: Create a Temporary NMDA Module</name> <t>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).</t> <sourcecode name="" type="yang"><![CDATA[ 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 }} ]]></sourcecode>}]]></sourcecode> </section> </section> </section> <section anchor="performance-considerations"> <name>Performance Considerations</name> <t>It is generally likely that certain YANG statements require more runtime resources than other statements. Although there are no performance requirements for YANG validation, the following information <bcp14>MAY</bcp14> be considered when designing YANG data models:</t> <ul spacing="normal"> <li> <t>Lists are generally more expensive than containers</t> </li> <li> <t>"when" statement evaluation is generally more expensive than "if-feature" or "choice" statements</t> </li> <li> <t>"must" statements are generally more expensive than "min-elements", "max-elements", "mandatory", or "unique" statements</t> </li> <li> <t>"identityref" leafs are generally more expensive than "enumeration" leafs</t> </li> <li> <t>"leafref" and "instance-identifier" types with "require-instance" set to "true" are generally more expensive than if "require-instance" is set to "false"</t> </li> </ul> </section> <section anchor="open-systems-considerations"> <name>Open Systems Considerations</name> <t>Only the modules imported by a particular module can be assumed to be present in an implementation. An open system <bcp14>MAY</bcp14> include any combination of YANG modules.</t> </section> <section anchor="guidelines-for-constructs-specific-to-yang-11"> <name>Guidelines for Constructs Specific to YANG 1.1</name> <!--[rfced] Is YANG 1.1 still considered "new"? It was published as RFC 7950 in August 2016. Original: The set of guidelines for YANG 1.1 will grow as operational experience is gained with the new language features. This section contains an initial set of guidelines for new YANG 1.1 language features. --> <t>The set of guidelines for YANG 1.1 will grow as operational experience is gained with the new language features. This section contains an initial set of guidelines for new YANG 1.1 language features.</t> <section anchor="importing-multiple-revisions"> <name>Importing Multiple Revisions</name> <t>Standard modules <bcp14>SHOULD NOT</bcp14> import multiple revisions of the same module into a module. This <bcp14>MAY</bcp14> be done if independent definitions (e.g., enumeration typedefs) from specific revisions are needed in the importing module.</t> </section> <section anchor="using-feature-logic"> <name>Using Feature Logic</name> <t>The YANG 1.1 feature logic is much more expressive than YANG 1.0. A "description" statement <bcp14>SHOULD</bcp14> describe the "if-feature" logic in text, to help readers understand the module.</t> <t>YANG features <bcp14>SHOULD</bcp14> be used instead of the "when" statement, if possible. Features are advertised by the server, and objects conditional by the "if-feature" statement are conceptually grouped together. There is no such commonality supported for "when" statements.</t> <t>Features generally require less server implementation complexity and runtime resources than objects that use "when" statements. Features are generally static (i.e., set when a module is loaded and not changed at runtime). However, every client edit might cause a "when" statement result to change.</t> </section> <section anchor="anyxml-versus-anydata"> <name>"anyxml" versus "anydata"</name> <t>The "anyxml" statement <bcp14>MUST NOT</bcp14> be used to represent a conceptual subtree of YANG data nodes. The "anydata" statement <bcp14>MUST</bcp14> be used for this purpose.</t> </section> <section anchor="action-versus-rpc"> <name>"action" versus "rpc"</name> <t>The use of "action" statements or "rpc" statements is a subjective design decision. RPC operations are not associated with any particular data node. Actions are associated with a specific data node definition. An "action" statement <bcp14>SHOULD</bcp14> be used if the protocol operation is specific to a subset of all data nodes instead of all possible data nodes.</t> <t>The same action name <bcp14>MAY</bcp14> be used in different definitions within different data node. For example, a "reset" action defined with a data node definition for an interface might have different parameters than for a power supply or a VLAN. The same action name <bcp14>SHOULD</bcp14> be used to represent similar semantics.</t> <t>The NETCONF Access Control Model (NACM) <xref target="RFC8341"/> does not support parameter-based access control for RPC operations. The user is given permission (or not) to invoke the RPC operation with any parameters. For example, if each client is only allowed to reset their own interface, then NACM cannot be used.</t> <t>For example, NACM cannot enforce access control based on the value of the "interface" parameter, only the "reset" operation itself:</t> <sourcecode name="" type="yang"><![CDATA[ rpc reset { input { leaf interface { type if:interface-ref; mandatory true; description "The interface to reset."; } }} ]]></sourcecode>}]]></sourcecode> <t>However, NACM can enforce access control for individual interface instances, using a "reset" action. If the user does not have read access to the specific "interface" instance, then it cannot invoke the "reset" action for that interface instance:</t> <sourcecode name="" type="yang"><![CDATA[ container interfaces { list interface { ... action reset { } }} ]]></sourcecode>}]]></sourcecode> </section> </section> <section anchor="updating-yang-modules-published-versus-unpublished"> <name>Updating YANG Modules (Published versus Unpublished)</name> <t>YANG modules can change over time. Typically, new data model definitions are needed to support new features. YANG update rules defined in <xref section="11" sectionFormat="of" target="RFC7950"/> <bcp14>MUST</bcp14> be followed for published modules. They <bcp14>MAY</bcp14> be followed for unpublished modules.</t> <t>The YANG update rules only apply to published module revisions. Each organization will have their own way to identify published work that is considered to be stable and unpublished work that is considered to be unstable. For example, in the IETF,thean RFCdocumentis used for published work, andthean I-D is used for unpublished work.</t> </section> <section anchor="sec-tags"> <name>Defining Standard Tags</name> <t><xref target="RFC8819"/> specifies a method for associating tags with YANG modules. Tags may be defined and associated at the time of moduledesign time,design, atimplementation time,the time of implementation, or via user administrative control. Design-time tags are indicated using the module-tag extension statement.</t> <t>A module <bcp14>MAY</bcp14> indicate, using module-tag extension statements, a set of tags that are to be automatically associated with it (i.e., not added through configuration).</t> <sourcecode name="" type="yang"><![CDATA[ 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"; // ...} ]]></sourcecode>}]]></sourcecode> <t>Authors can use existing standard tags or use new tags defined in the model definition, as appropriate. For IETF modules, new tags <bcp14>MUST</bcp14> be assigned in the IANA "IETF YANG Module Tags" registry within the "YANG Module Tags" registry group <xref target="IANA-TAGS"/>.</t> </section> <section anchor="modeling-abstract-data-structures"> <name>Modeling Abstract Data Structures</name> <t>For contexts where YANG is used to model abstract data structures (e.g., protocol messages), the use of the "structure" extension statement <xref target="RFC8791"/> is <bcp14>RECOMMENDED</bcp14> compared to the "yang-data" extension statement <xreftarget="RFC8040"/>.</t> <ul empty="true"> <li> <t>Examplestarget="RFC8040"/>. Examples of modules that rely upon the "structure" extension statement from <xref target="RFC8791"/>arecan be found in <xref target="RFC9132"/> or <xref target="RFC9195"/>.</t></li> </ul><t>Abstract data structures can be augmented using the "augment-structure" statement <xreftarget="RFC8791"/>.</t> <ul empty="true"> <li> <t>Examplestarget="RFC8791"/>. Examples of modules that augment abstract data structuresarecan be found in <xref target="RFC9244"/> and <xref target="RFC9362"/>.</t></li> </ul></section> <section anchor="iana-maintained-modules"> <name>IANA-Maintained Modules</name> <section anchor="context"> <name>Context</name> <t>IANA maintains a set of registries that are key for interoperability. The content of these registriesareis usually available using various formats (e.g., plaintext,text or XML). However, therewerewas some confusion in the past about whether the content of some registries is dependent on a specific representation format. For example,Section 5 of<xreftarget="RFC8892"/>target="RFC8892" section="5"/> was published to clarify that MIB and YANG modules are merely additional formats in which the "Interface Types (ifType)" and "Tunnel Types (tunnelType)" registries are available. The MIB <xref target="RFC2863"/> and YANG modules (<xref target="RFC7224"/> <xreftarget="RFC7224"/><xref target="RFC8675"/>target="RFC8675"/>) are not separate registries, and the same values are always present in all formats of the same registry.</t> <t>Adesign,design in which a YANG module includes parameters and values directly in a module that is not maintained by IANA while these are populated in an IANAregistry,registry could lead to ambiguity and maintain stale information. Such a design creates another source of information that may deviate from the IANA registry as new values are assigned or some values are deprecated.</t> <t>For the sake of consistency and the ability to support new values while maintaining IANA registries as the unique authoritative source of information, this document recommends the use of IANA-maintained modules as the single source of information.</t> <t>The following section provides a set of guidelines for YANG module authors related to the design of IANA-maintained modules. These guidelines are meant to leverage existing IANA registries and use YANG as another format to present the content of these registries when appropriate.</t> </section> <section anchor="guidelines-for-iana-maintained-modules"> <name>Guidelines for IANA-Maintained Modules</name> <t>When designing a YANG module for a functionality governed by a protocol for which IANA maintains a registry, it is <bcp14>RECOMMENDED</bcp14> to specify an IANA-maintained module that echoes the content of that registry. This is superior to including that content in an IETF-maintained module.</t> <t>When one or multiple registries are available under the same registry group, it is <bcp14>RECOMMENDED</bcp14> to define an IANA-maintained module for each registry. However, module designers <bcp14>MAY</bcp14> consider defining one single IANA-maintained module that covers all registries if maintaining that single module is manageable (e.g., very few values are present or expected to be present for each registry). An example of such a module is documented in <xref section="5.2" sectionFormat="of" target="RFC9132"/>.</t> <t>An IANA-maintained module may use the "identityref" data type (e.g., <xref target="RFC8675"/>) or an enumeration data type (e.g., <xref target="RFC9108"/>). See <xref target="sec-fve"/> for a guidance on which data type to use. The decision about which type to use should be made based upon specifics related to the intended use of the IANA-maintained module. For example, identities are useful if the registry entries are organized hierarchically, possibly including multiple inheritances. The reasoning for the design choice <bcp14>MUST</bcp14> be documented in the companion specification that registers an IANA-maintained module. For example, <xref target="RFC9244"/> defines an IANA-maintained module that uses enumerations for the following reason:</t> <blockquote> <t>The DOTS telemetry module (Section11.1)<xref target="RFC9244" section="11.1" sectionFormat="bare"/>) 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.</t> </blockquote><t>Designers<!--[rfced] Section 4.30.2: Would you like to update these two paragraphs to make them more aligned? Or remove some text to reduce redundancy? To paraphrase: (A) says the I-D MAY supply the module or only a script. (B) says the I-D SHOULD supply the module when a script is used. A) Original (paragraph 5): Designers of IANA-maintained modules<bcp14>MAY</bcp14>MAY supply the full initial 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 (e.g., an XSLT stylesheet as in Appendix A of [RFC9108] or a Python script as in [RFC9645]). For both cases, the document that defines an IANA-maintained module MUST include a note indicating that the document is only documenting the initial version of the module and that the authoritative version is to be retrieved from the IANA registry B) Original (paragraph 7): It is RECOMMENDED to include the URL from where to retrieve the recent version of the module. When a script is used, the Internet- Draft that defines an IANA-maintained module have to include an appendix with the full script and SHOULD include an appendix with the initial full version of the module. Including such an appendix in pre-RFC versions is meant to assess the correctness of the outcome of the supplied script. 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 RFC and that RFC IIII is replaced with the RFC number that is assigned to the document. Also: - May "in pre-RFC versions" be changed to "in Internet-Drafts"? - May the phrases (A) "full initial version" and (B) "initial full version" of the module be made consistent? They seemingly refer to the same concept. --> <t>Designers of IANA-maintained modules <bcp14>MAY</bcp14> supply the full initial 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 (e.g., an Extensible Stylesheet Language Transformations (XSLT) stylesheet as in <xref section="A" target="RFC9108"/> or a Python script as in <xref target="RFC9645"/>). For both cases, the document that defines an IANA-maintained module <bcp14>MUST</bcp14> include a note indicating that the document is only documenting the initial version of the module and that the authoritative version is to be retrieved from the IANA registry. Also, the IANA-maintained module <bcp14>MUST</bcp14> include the following note indicating the RFC that registered the initial version of the IANA-maintained module:</t><ul empty="true"> <li> <t>The<blockquote><t>The initial version of this YANG module is part of RFC IIII; see the RFC itself for full legalnotices.</t> </li> </ul>notices.</t></blockquote> <t>It is <bcp14>RECOMMENDED</bcp14> to include the URL from where to retrieve the recent version of the module. When a script is used, the Internet-Draft that defines an IANA-maintained modulehavehas to include an appendix with the full script and <bcp14>SHOULD</bcp14> include an appendix with the initial full version of the module. Including such an appendix in pre-RFC versions is meant to assess the correctness of the outcome of the supplied script. The authors <bcp14>MUST</bcp14> include a note to the RFC Editor requesting that the appendix with the initial version of the module be removed before publication as RFC and that RFC IIII is replaced with the RFC number that is assigned to the document. Initial versions of IANA-maintained modules that are published in RFCs may be misused despite the appropriate language to refer to the IANA registry to retrieve the up-to-date module. This is problematic for interoperability, e.g., when values are deprecated or are associated with a new meaning.</t><artwork><![CDATA[ Note: [Style]<aside><t>Note: <xref target="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 module based upon the XML representation of an IANAregistry. ]]></artwork>registry.</t></aside> <t>If an IANA-maintained module is imported by another module, a normative reference with the IANA URL fromwherewhich to retrieve the IANA-maintained module <bcp14>SHOULD</bcp14> be included. Although not encouraged, referencing the RFC that defines the initial version of the IANA module is acceptable in specific cases (e.g., the imported version is specifically the initial version, the RFC includes useful description about the usage of the module).</t> <!--[rfced] Would you like to update this paragraph about URLs so that the URLs are shown, rather than in references? (This would be a change from xref to eref elements.) Original: Examples of IANA URLs from which to retrieve the latest version of an IANA-maintained module are as follows: [IANA_BGP-L2_URL], [IANA_PW-Types_URL], and [IANA_BFD_URL]. "IANA_FOO_URL" is used in the following to refer to such URLs. These URLs are expected to be sufficiently permanent and stable. Whenever referencing a specific version of an IANA-maintained module is needed, then URLs such as [IANA_BGP-L2_URL-Revision] are used. "IANA_FOO_URL_With_REV" is used in the following to refer to such URLs. Perhaps: Examples of IANA URLs from which to retrieve the latest version of an IANA-maintained module are as follows: <https://www.iana.org/assignments/iana-bgp-l2-encaps> <https://www.iana.org/assignments/iana-pseudowire-types> <https://www.iana.org/assignments/iana-bfd-types> "IANA_FOO_URL" is used in the following to refer to such URLs. These URLs are expected to be sufficiently permanent and stable. Whenever referencing a specific version of an IANA-maintained module is needed, then URLs such as the following are used: <https://www.iana.org/assignments/yang-parameters/iana-bfd-types@ 2021-10-21.yang> "IANA_FOO_URL_With_REV" is used in the following to refer to such URLs. --> <t>Examples of IANA URLs fromwherewhich to retrieve the latest version of an IANA-maintained moduleare:are as follows: <xref target="IANA_BGP-L2_URL"/>, <xref target="IANA_PW-Types_URL"/>, and <xref target="IANA_BFD_URL"/>. "IANA_FOO_URL" is used in the following to refer to such URLs. These URLs are expected to be sufficiently permanent and stable. Whenever referencing a specific version of an IANA-maintained module is needed, then URLs such as <xref target="IANA_BGP-L2_URL-Revision"/> are used. "IANA_FOO_URL_With_REV" is used in the following to refer to such URLs.</t> <t>A template for IANA-maintained modules is provided in <xref target="tem-iana"/>.</t> </section> <section anchor="sec-iana-mm"> <name>Guidance for Writing the IANA Considerations for RFCs Defining IANA-Maintained Modules</name> <t>In addition to the IANA considerations in <xref target="sec-iana-cons"/>, the IANA ConsiderationsSectionsection of an RFC that includes an IANA-maintained module <bcp14>MUST</bcp14> provide the required instructions for IANA to automatically perform the maintenance of that IANA module. These instructions describe how to proceed with updates to the IANA-maintained module that are triggered by a change to the authoritative registry. Concretely, the IANA ConsiderationsSectionsection <bcp14>SHALL</bcp14> at least provide the following information:</t> <ul spacing="normal"> <li> <t>A request to IANA to add a note to the page displaying the information about the IANA-maintained module that new values must not be directly added to the module. These values should be added to an authoritative IANA registry.</t> </li> <li> <t>A request to IANA to add a note to the authoritative IANA registry to indicate that any change to the registry must be reflected into the corresponding IANA-maintained module. That is, any changes to the registry must be accompanied by an update to the corresponding IANA-maintained module.</t> </li> <li> <t>Details about the required actions (e.g., add a new "identity" or "enum" statement) to update the IANA-maintained module to reflect changes to an authoritative IANA registry. Typically, these details have to include the procedure to create a new "identity" statement name and substatements ("base", "status", "description", and "reference") or a new "enum" statement andsub-statementssubstatements ("value", "status", "description", and "reference"). </t> <ul spacing="normal"> <li> <t>When creating a new "identity" statement name or a new "enum" statement, it is <bcp14>RECOMMENDED</bcp14> to use the same name (if present) as recorded in the IANA registry.</t> </li> <li> <!--[rfced] Might this update capture your intended meaning? Note: similar text occurs more than once. Original: Specifically, if the name begins with a number, it is RECOMMENDED to spell out (i.e., write in full) the number when used as an identifier. Perhaps: Specifically, if the name begins with a number, it is RECOMMENDED to spell out (i.e., not use a digit) the number when used as an identifier. --> <t>If the name in the IANA registry does not comply with the naming conventions listed in <xref target="sec-id-naming"/>, the procedure <bcp14>MUST</bcp14> detail how IANA can generate legal identifiers from such a name. Specifically, if the name begins with a number, it is <bcp14>RECOMMENDED</bcp14> to spell out (i.e., write in full) the number when used as an identifier. IANA should be provided with instructions to perform such a task. For example, authors of a module with such identifiers have to indicate whether: </t> <ul spacing="normal"> <li> <t>"3des-cbc" should be "three-des-cbc" or rather "triple-des-cbc" to be consistent with <xref section="6.3" sectionFormat="of" target="RFC4253"/>.</t> </li> <li> <t>"6to4" should be "sixToFour" as in <xref target="RFC7224"/> or "sixtofour" as in <xref target="RFC8675"/>.</t> </li> </ul> </li> <li> <t>If a new registration uses an identifier that does not comply with the naming conventions listed in <xref target="sec-id-naming"/>, IANA should check ifaguidance to generate legal identifiers was supplied in the RFC that specified the initial version of the module. If no such guidance is available, IANA should check the latest revision of the IANA-maintained module for similar patterns. If all elsefailed,fails, IANA should seek advice from relevant registry experts (e.g., designated experts for a registrywithusing the Expert Review policy (<xref section="4.5" sectionFormat="of" target="RFC8126"/>) or responsibleArea Director).</t>area director).</t> </li> </ul> </li> <li> <t>A note that unassigned or reserved values must not be present in the IANA-maintained module.</t> </li> <li> <t>An instruction whether experimental values should be included in the IANA-maintained module. If no instruction is provided, experimental values <bcp14>MUST NOT</bcp14> be listed in the IANA-maintained module.</t> </li> <li> <t>An instruction about how to generate the "revision" statement.</t> </li> </ul> <t>A template for the IANA Considerations is provided in <xref target="sec-temp-id"/> for IANA-maintained modules with identities and <xref target="sec-temp-enum"/> for IANA-maintained modules with enumerations. Authors may modify the template to reflect specifics of their modules (e.g., multiple registries can be listed for a single IANA-maintained module, no explicit description (or name) field is listed under the authoritative IANA registry, or the name does not comply with YANG naming conventions (<xref target="sec-id-naming"/>)).</t> <t>An example of "revision" statements that are generated following the guidance in <xref target="sec-temp-id"/> is provided below:</t> <sourcecode name="" type="yang"><![CDATA[ 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";} ]]></sourcecode>}]]></sourcecode> <t>Duplicating the same reference at the high level and at the level of a new addition might be redundant. For example, the following does not provide access to a specific (OLD) revision of the module when future revisions are made <xref target="IANA_Tunnel_Type_URL"/>:</t> <sourcecode name="" type="yang"><![CDATA[ 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"IPsec tunnel mode encapsulation."; reference "RFC 4301: Security Architecture for the Internet Protocol";} ]]></sourcecode>}]]></sourcecode> <t>The following example shows how to generate the "revision" statements following the guidance in <xref target="sec-temp-id"/>:</t> <sourcecode name="" type="yang"><![CDATA[ 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"IPsec tunnel mode encapsulation."; reference "RFC 4301: Security Architecture for the Internet Protocol";} ]]></sourcecode>}]]></sourcecode> <t>Thefollowingtemplates in the following subsections are to be considered in addition to the required information that is provided in <xref target="sec-iana-cons"/>.</t> <section anchor="sec-temp-id"> <name>Template for IANA-Maintained Modules with Identities</name><sourcecode markers="true"><![CDATA[<artwork><![CDATA[ <CODE BEGINS> 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 "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 followingsub-statementssubstatements 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. Unassigned or reserved values are not present in the module. When the "iana-foo" YANG module is updated, a new "revision" statement with a unique revision date must be added in front of the existingrevision"revision" statements. The "revision" statement MUST contain both "description" and "reference" substatements as follows. The "description" substatement captures what changed in the revised version. Typically, the description enumerates the changes such as udpates to existing entries (e.g., update a description or a reference) or notes which identities were added or had their status changed (e.g., deprecated, discouraged, or obsoleted). -- When such a description is not feasible, the description varies -- on how the update is triggered. -- If the update is triggered by an RFC, insert this text: The "description" substatement should include this text: "Applied updates as specified by RFC XXXX.". -- If the update is triggered following other IANA registration -- policy (Section 4 of [RFC8126]) but not all the values in the -- registry are covered by the same policy, insert this text: The "description" substatement should include this text: "Applied updates as specified by the registration policy <Some_IANA_policy>". The "reference" substatement points specifically to the published module (i.e., IANA_FOO_URL_With_REV). It may also point to an authoritative event triggering the update to the YANG module. In all cases, this event is cited from the underlying IANA registry. If the update is triggered by an RFC, that RFC must also be included in the "reference" substatement. -- 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. 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.]]></sourcecode><CODE ENDS> ]]></artwork> </section> <section anchor="sec-temp-enum"> <name>Template for IANA-Maintained Modules with Enumerations</name><sourcecode markers="true"><![CDATA[<artwork><![CDATA[ <CODE BEGINS> 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, andsub-statementssubstatements 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 with the title of the document(s) added. Unassigned or reserved values are not present in the module. When the "iana-foo" YANG module is updated, a new "revision" statement with a unique revision date needs to be added in front of the existingrevision"revision" statements. The "revision" statement MUST contain both "description" and "reference" substatements as follows. The "description" substatement captures what changed in the revised version. Typically, the description enumerates the changes such as udpates to existing entries (e.g., update a description or a reference) or notes which "enums" were added or had their status changed (e.g., deprecated, discouraged, or obsoleted). -- When such a description is not feasible, the description varies -- on how the update is triggered. -- If the update is triggered by an RFC, insert this text: The "description" substatement should include this text: "Applied updates as specified by RFC XXXX.". -- If the update is triggered following other IANA registration -- policy (Section 4 of [RFC8126]) but not all the values in the -- registry are covered by the same policy, insert this text: The "description" substatement should include this text: "Applied updates as specified by the registration policy <Some_IANA_policy>". The "reference" substatement points specifically to the published module (i.e., IANA_FOO_URL_With_REV). It may also point to an authoritative event triggering the update to the YANG module. In all cases, this event is cited from the underlying IANA registry. If the update is triggered by an RFC, that RFC must also be included in the "reference" substatement. -- 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. 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.]]></sourcecode><CODE ENDS> ]]></artwork> </section> </section> </section> </section> <section anchor="sec-iana"> <name>IANA Considerations</name> <section anchor="yang-modules"> <name>YANG Modules</name> <t>The following registration in the "ns" registry of the "IETF XML Registry" registry group <xref target="RFC3688"/> was detailed in <xref target="RFC8407"/>.This document requestsIANAto updatehas updated this registration to reference this document.</t><artwork><![CDATA[ URI: urn:ietf:params:xml:ns:yang:ietf-template Registrant Contact: The IESG. XML: N/A,<dl spacing="compact" newline="false"> <dt>URI:</dt><dd>urn:ietf:params:xml:ns:yang:ietf-template</dd> <dt>Registrant Contact:</dt><dd>The IESG</dd> <dt>XML:</dt><dd>N/A; the requested URI is an XMLnamespace. ]]></artwork>namespace.</dd> </dl> <t>IANAis requested to registerhas registered the following URI in the "ns" registry within the "IETF XML Registry" registry group <xref target="RFC3688"/>:</t><artwork><![CDATA[ URI: urn:ietf:params:xml:ns:yang:iana-template Registrant Contact: The IESG. XML: N/A;<dl spacing="compact" newline="false"> <dt>URI:</dt><dd>urn:ietf:params:xml:ns:yang:iana-template</dd> <dt>Registrant Contact:</dt><dd>The IESG</dd> <dt>XML:</dt><dd>N/A; the requested URI is an XMLnamespace. ]]></artwork> <t>This document requests IANA to registernamespace.</dd> </dl> <t>IANA has registered the following YANG modules in the "YANG Module Names" registry <xref target="RFC6020"/> within the "YANG Parameters" registry group.</t><artwork><![CDATA[ Name: ietf-template Maintained by IANA? N Namespace: urn:ietf:params:xml:ns:yang:ietf-template Prefix: temp Reference: RFC AAAA Name: iana-template Maintained by IANA? N Namespace: urn:ietf:params:xml:ns:yang:iana-template Prefix: iana-foo Reference: RFC AAAA ]]></artwork><dl spacing="compact" newline="false"> <dt>Name:</dt><dd>ietf-template</dd> <dt>Maintained by IANA?</dt><dd>N</dd> <dt>Namespace:</dt><dd>urn:ietf:params:xml:ns:yang:ietf-template</dd> <dt>Prefix:</dt><dd>temp</dd> <dt>Reference:</dt><dd>RFC 9907</dd> </dl> <dl spacing="compact" newline="false"> <dt>Name:</dt><dd>iana-template</dd> <dt>Maintained by IANA?</dt><dd>N</dd> <dt>Namespace:</dt><dd>urn:ietf:params:xml:ns:yang:iana-template</dd> <dt>Prefix:</dt><dd>iana-foo</dd> <dt>Reference:</dt><dd>RFC 9907</dd> </dl> </section> <section anchor="update-yang-parameters-registry-group"> <name>Update in YANG Parameters Registry Group</name><t>Also, this document requests IANA to update<t>For theRFC8407 reference forreferences of the "YANG Module Names" registry under the "YANG Parameters" registrygroup to point to the RFC number that will be assignedgroup, IANA has updated <xref target="RFC8407"/> to thisdocumentdocument, as it contains the template necessary for registration inAppendix B.</t><xref target="tem-ietf"/>.</t> </section> <section anchor="iana-maintained-modules-1"> <name>IANA-Maintained Modules</name> <t>IANA should refer to <xref target="sec-iana-mm"/> for information necessary to populate "revision" statements and "identity" and "enum" substatements in IANA-maintained modules. These considerations cover both the creation and maintenance of an IANA-mainatined module. In particular, the following should be noted:</t> <ul spacing="normal"> <li> <t>When an underlying registration is deprecated or obsoleted, a corresponding "status" substatement should be added to the identity or enumeration statement.</t> </li> <li> <t>The "reference" substatement 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 the "reference" substatement. It may also point to an authoritative event triggering the update to the YANG module. In all cases, the event is cited from the underlying IANA registry.</t> </li> </ul> <t>In addition, when the module is published, IANA must add the following notes to:</t> <dl newline="true"> <dt>The YANG Module Names registry:</dt> <dd> <t>New values must not be directly added to the "iana-foo" YANG module. They must instead be added to the "foo" registry.</t> </dd> <dt>The underlying registry:</dt> <dd> <t>When this registry is modified, the YANG module "iana-foo" [IANA_FOO_URL] must be updated as defined in RFC IIII.</t> </dd> </dl> </section> </section> <section anchor="operations-and-manageability-considerations"> <name>Operations and Manageability Considerations</name> <t>Although the document focuses on YANG data modeling language guidance, the document does not define a protocol or a protocol extension. As such, there are no new operations or manageability requirements introduced by this document.</t> </section> <section anchor="security-considerations"> <name>Security Considerations</name> <t>This document defines guidelines for NETCONF or RESTCONF content defined with the YANG data modeling language. It does not introduce any new or increased security risks.</t> </section> </middle> <back> <references anchor="sec-combined-references"> <name>References</name> <references anchor="sec-normative-references"> <name>Normative References</name> <reference anchor="W3C.REC-xpath" target="https://www.w3.org/TR/1999/REC-xpath-19991116"> <front> <title>XML Path Language (XPath) Version 1.0</title> <author initials="J." surname="Clark" fullname="JamesClark">Clark" role="editor"> <organization/> </author> <author initials="S." surname="DeRose" fullname="SteveDeRose">DeRose" role="editor"> <organization/> </author> <date day="16" year="1999" month="November"/> </front><seriesInfo name="W3C" value="Recommendation REC-xpath-19991116"/><refcontent>W3C Recommendation</refcontent> </reference> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6241.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8040.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7950.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6020.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8791.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8126.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7952.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8792.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8819.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8342.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8341.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3688.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5378.xml"/> </references> <references anchor="sec-informative-references"> <name>Informative References</name> <referenceanchor="RFC6241">anchor="IANA-MOD-NAMES" target="https://www.iana.org/assignments/yang-parameters/"> <front><title>Network Configuration Protocol (NETCONF)</title> <author fullname="R. Enns" initials="R." role="editor" surname="Enns"/> <author fullname="M. Bjorklund" initials="M." role="editor" surname="Bjorklund"/> <author fullname="J. Schoenwaelder" initials="J." role="editor" surname="Schoenwaelder"/> <author fullname="A. Bierman" initials="A." role="editor" surname="Bierman"/> <date month="June" year="2011"/> <abstract> <t>The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK]</t> </abstract><title>YANG Module Names</title> <author> <organization>IANA</organization> </author> <date/> </front><seriesInfo name="RFC" value="6241"/> <seriesInfo name="DOI" value="10.17487/RFC6241"/></reference> <referenceanchor="RFC8040">anchor="IANA-XML" target="https://www.iana.org/assignments/xml-registry/"> <front><title>RESTCONF Protocol</title> <author fullname="A. Bierman" initials="A." surname="Bierman"/> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <author fullname="K. Watsen" initials="K." surname="Watsen"/> <date month="January" year="2017"/> <abstract> <t>This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined<title>IETF XML Registry</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <!-- [rfced] FYI- The reference [RFC-STYLE] was not cited inYANG, usingthedatastore concepts defineddocument (though it was in RFC 8407), so we have removed theNetwork Configuration Protocol (NETCONF).</t> </abstract>reference entry. Please let us know any objections. --> <reference anchor="IANA_BFD_URL" target="https://www.iana.org/assignments/iana-bfd-types"> <front> <title>iana-bfd-types YANG Module</title> <author> <organization>IANA</organization> </author> <date/> </front><seriesInfo name="RFC" value="8040"/> <seriesInfo name="DOI" value="10.17487/RFC8040"/></reference> <referenceanchor="RFC7950">anchor="IANA_BGP-L2_URL" target="https://www.iana.org/assignments/iana-bgp-l2-encaps"> <front><title>The YANG 1.1 Data Modeling Language</title> <author fullname="M. Bjorklund" initials="M." role="editor" surname="Bjorklund"/> <date month="August" year="2016"/> <abstract> <t>YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from<title>iana-bgp-l2-encaps YANGversion 1. This document also specifies theModule</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_BGP-L2_URL-Revision" target="https://www.iana.org/assignments/yang-parameters/iana-bfd-types@2021-10-21.yang"> <front> <title>iana-bfd-types@2021-10-21.yang</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_PW-Types_URL" target="https://www.iana.org/assignments/iana-pseudowire-types"> <front> <title>iana-pseudowire-types YANGmappings to the Network Configuration Protocol (NETCONF).</t> </abstract>Module</title> <author> <organization>IANA</organization> </author> <date/> </front><seriesInfo name="RFC" value="7950"/> <seriesInfo name="DOI" value="10.17487/RFC7950"/></reference> <referenceanchor="RFC6020">anchor="Style" target="https://github.com/llhotka/iana-yang"> <front><title>YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)</title> <author fullname="M. Bjorklund" initials="M." role="editor" surname="Bjorklund"/><title>IANA YANG</title> <author> <organization/> </author> <datemonth="October" year="2010"/> <abstract> <t>YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK]</t> </abstract>month="Dec" year="2021"/> </front><seriesInfo name="RFC" value="6020"/> <seriesInfo name="DOI" value="10.17487/RFC6020"/><refcontent>commit 3a6cb69</refcontent> </reference> <referenceanchor="RFC8791">anchor="IANA-YANG-PARAMETERS" target="https://www.iana.org/assignments/yang-parameters"> <front> <title>YANGData Structure Extensions</title> <author fullname="A. Bierman" initials="A." surname="Bierman"/> <author fullname="M. Björklund" initials="M." surname="Björklund"/> <author fullname="K. Watsen" initials="K." surname="Watsen"/> <date month="June" year="2020"/> <abstract> <t>This document describesParameters</title> <author> <organization>IANA</organization> </author> </front> </reference> <reference anchor="IANA-TAGS" target="https://www.iana.org/assignments/yang-module-tags/"> <front> <title>YANG Module Tags</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_Tunnel_Type_URL" target="https://www.iana.org/assignments/iana-tunnel-type"> <front> <title>iana-tunnel-type YANGmechanisms for defining abstract data structures with YANG.</t> </abstract>Module</title> <author> <organization>IANA</organization> </author> <date/> </front><seriesInfo name="RFC" value="8791"/> <seriesInfo name="DOI" value="10.17487/RFC8791"/></reference> <referenceanchor="RFC8126">anchor="ID-Guidelines" target="https://authors.ietf.org/en/content-guidelines-overview"> <front><title>Guidelines for Writing an IANA Considerations Section in RFCs</title> <author fullname="M. Cotton" initials="M." surname="Cotton"/> <author fullname="B. Leiba" initials="B." surname="Leiba"/> <author fullname="T. Narten" initials="T." surname="Narten"/> <date month="June" year="2017"/> <abstract> <t>Many protocols make use of points of extensibility that use constants<title>Content guidelines overview</title> <author> <organization>IETF</organization> </author> </front> </reference> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8407.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8675.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9291.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2026.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8340.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8309.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9129.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7407.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8349.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6991.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8969.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8299.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8466.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9182.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8199.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8519.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4252.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9000.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7951.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5737.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3849.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9637.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5612.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5398.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2606.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4151.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8343.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7223.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9132.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9195.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9244.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9362.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8892.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2863.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7224.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9108.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9645.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4253.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4181.xml"/> <reference anchor="Err5693" quote-title="false" target="https://www.rfc-editor.org/errata/eid5693"> <front> <title>Erratum ID 5693</title> <author> <organization>RFC Errata</organization> </author> </front> <refcontent>RFC 8407</refcontent> </reference> <reference anchor="Err5800" quote-title="false" target="https://www.rfc-editor.org/errata/eid5800"> <front> <title>Erratum ID 5800</title> <author> <organization>RFC Errata</organization> </author> </front> <refcontent>RFC 8407</refcontent> </reference> <reference anchor="Err6899" quote-title="false" target="https://www.rfc-editor.org/errata/eid6899"> <front> <title>Erratum ID 6899</title> <author> <organization>RFC Errata</organization> </author> </front> <refcontent>RFC 8407</refcontent> </reference> <reference anchor="Err7416" quote-title="false" target="https://www.rfc-editor.org/errata/eid7416"> <front> <title>Erratum ID 7416</title> <author> <organization>RFC Errata</organization> </author> </front> <refcontent>RFC 8407</refcontent> </reference> </references> </references> <section anchor="module-review-checklist"> <name>Module Review Checklist</name> <t>This section is adapted from <xref target="RFC4181"/>.</t> <!--[rfced] For "I-D Boilerplate", would you like toidentify various protocol parameters. To ensure thatpoint to to https://authors.ietf.org/required-content ? It seems more relevant than thevalues in these fields do not have conflicting uses andbroad page that https://www.ietf.org/id-info/guidelines.html resolves topromote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols,(https://authors.ietf.org/en/content-guidelines-overview). Original: * I-D Boilerplate: Verify thatrole is filled bytheInternet Assigned Numbers Authority (IANA).</t> <t>To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry.</t> <t>This is the third edition of this document; it obsoletes RFC 5226.</t> </abstract> </front> <seriesInfo name="BCP" value="26"/> <seriesInfo name="RFC" value="8126"/> <seriesInfo name="DOI" value="10.17487/RFC8126"/> </reference> <reference anchor="RFC7952"> <front> <title>Defining and Using Metadata with YANG</title> <author fullname="L. Lhotka" initials="L." surname="Lhotka"/> <date month="August" year="2016"/> <abstract> <t>This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes.</t> </abstract> </front> <seriesInfo name="RFC" value="7952"/> <seriesInfo name="DOI" value="10.17487/RFC7952"/> </reference> <reference anchor="RFC8792"> <front> <title>Handling Long Lines in Content of Internet-Drafts and RFCs</title> <author fullname="K. Watsen" initials="K." surname="Watsen"/> <author fullname="E. Auerswald" initials="E." surname="Auerswald"/> <author fullname="A. Farrel" initials="A." surname="Farrel"/> <author fullname="Q. Wu" initials="Q." surname="Wu"/> <date month="June" year="2020"/> <abstract> <t>This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content.</t> </abstract> </front> <seriesInfo name="RFC" value="8792"/> <seriesInfo name="DOI" value="10.17487/RFC8792"/> </reference> <reference anchor="RFC8819"> <front> <title>YANG Module Tags</title> <author fullname="C. Hopps" initials="C." surname="Hopps"/> <author fullname="L. Berger" initials="L." surname="Berger"/> <author fullname="D. Bogdanovic" initials="D." surname="Bogdanovic"/> <date month="January" year="2021"/> <abstract> <t>This document provides for the association of tags with YANG modules. The expectation is for such tags to be used to help classify and organize modules. A method for defining, reading, and writing modules tags is provided. Tags may be registered and assigned during module definition, assigned by implementations, or dynamically defined and set by users. This document also provides guidance to future model writers; as such, this document updates RFC 8407.</t> </abstract> </front> <seriesInfo name="RFC" value="8819"/> <seriesInfo name="DOI" value="10.17487/RFC8819"/> </reference> <reference anchor="RFC8342"> <front> <title>Network Management Datastore Architecture (NMDA)</title> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <author fullname="J. Schoenwaelder" initials="J." surname="Schoenwaelder"/> <author fullname="P. Shafer" initials="P." surname="Shafer"/> <author fullname="K. Watsen" initials="K." surname="Watsen"/> <author fullname="R. Wilton" initials="R." surname="Wilton"/> <date month="March" year="2018"/> <abstract> <t>Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950.</t> </abstract> </front> <seriesInfo name="RFC" value="8342"/> <seriesInfo name="DOI" value="10.17487/RFC8342"/> </reference> <reference anchor="RFC2119"> <front> <title>Key words for use in RFCs to Indicate Requirement Levels</title> <author fullname="S. Bradner" initials="S." surname="Bradner"/> <date month="March" year="1997"/> <abstract> <t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t> </abstract> </front> <seriesInfo name="BCP" value="14"/> <seriesInfo name="RFC" value="2119"/> <seriesInfo name="DOI" value="10.17487/RFC2119"/> </reference> <reference anchor="RFC8174"> <front> <title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title> <author fullname="B. Leiba" initials="B." surname="Leiba"/> <date month="May" year="2017"/> <abstract> <t>RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.</t> </abstract> </front> <seriesInfo name="BCP" value="14"/> <seriesInfo name="RFC" value="8174"/> <seriesInfo name="DOI" value="10.17487/RFC8174"/> </reference> <reference anchor="RFC8341"> <front> <title>Network Configuration Access Control Model</title> <author fullname="A. Bierman" initials="A." surname="Bierman"/> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <date month="March" year="2018"/> <abstract> <t>The standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) or the RESTCONF protocol requires a structured and secure operating environment that promotes human usability and multi-vendor interoperability. There is a need for standard mechanisms to restrict NETCONF or RESTCONF protocol access for particular users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. Thisdocumentdefines such an access control model.</t> <t>This document obsoletes RFC 6536.</t> </abstract> </front> <seriesInfo name="STD" value="91"/> <seriesInfo name="RFC" value="8341"/> <seriesInfo name="DOI" value="10.17487/RFC8341"/> </reference> <reference anchor="RFC3688"> <front> <title>The IETF XML Registry</title> <author fullname="M. Mealling" initials="M." surname="Mealling"/> <date month="January" year="2004"/> <abstract> <t>This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas.</t> </abstract> </front> <seriesInfo name="BCP" value="81"/> <seriesInfo name="RFC" value="3688"/> <seriesInfo name="DOI" value="10.17487/RFC3688"/> </reference> <reference anchor="RFC3986"> <front> <title>Uniform Resource Identifier (URI): Generic Syntax</title> <author fullname="T. Berners-Lee" initials="T." surname="Berners-Lee"/> <author fullname="R. Fielding" initials="R." surname="Fielding"/> <author fullname="L. Masinter" initials="L." surname="Masinter"/> <date month="January" year="2005"/> <abstract> <t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK]</t> </abstract> </front> <seriesInfo name="STD" value="66"/> <seriesInfo name="RFC" value="3986"/> <seriesInfo name="DOI" value="10.17487/RFC3986"/> </reference> <reference anchor="RFC5378"> <front> <title>Rights Contributors Provide to the IETF Trust</title> <author fullname="S. Bradner" initials="S." role="editor" surname="Bradner"/> <author fullname="J. Contreras" initials="J." role="editor" surname="Contreras"/> <date month="November" year="2008"/> <abstract> <t>The IETF policies about rights in Contributions to the IETF are designed to ensure that such Contributions can be made available to the IETF and Internet communities while permitting the authors to retain as many rights as possible. This memo details the IETF policies on rights in Contributions to the IETF. It also describes the objectives that the policies are designed to meet. This memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and RFC 5377, replaces Section 10 of RFC 2026. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t> </abstract> </front> <seriesInfo name="BCP" value="78"/> <seriesInfo name="RFC" value="5378"/> <seriesInfo name="DOI" value="10.17487/RFC5378"/> </reference> </references> <references anchor="sec-informative-references"> <name>Informative References</name> <reference anchor="IANA-MOD-NAMES" target="https://www.iana.org/assignments/yang-parameters/"> <front> <title>YANG Module Names</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA-XML" target="https://www.iana.org/assignments/xml-registry/"> <front> <title>IETF XML Registry</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="RFC-STYLE" target="https://www.rfc-editor.org/styleguide/"> <front> <title>Style Guide</title> <author> <organization>RFC Editor</organization> </author> <date/> </front> </reference> <reference anchor="IANA_BFD_URL" target="https://www.iana.org/assignments/iana-bfd-types/iana-bfd-types.xhtml"> <front> <title>iana-bfd-types YANG Module</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_BGP-L2_URL" target="https://www.iana.org/assignments/iana-bgp-l2-encaps/iana-bgp-l2-encaps.xhtml"> <front> <title>iana-bgp-l2-encaps YANG Module</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_BGP-L2_URL-Revision" target="https://www.iana.org/assignments/yang-parameters/iana-bfd-types@2021-10-21.yang"> <front> <title>iana-bfd-types@2021-10-21.yang</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_PW-Types_URL" target="https://www.iana.org/assignments/iana-pseudowire-types/iana-pseudowire-types.xhtml"> <front> <title>iana-pseudowire-types YANG Module</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="Style" target="https://github.com/llhotka/iana-yang"> <front> <title>IANA YANG</title> <author> <organization/> </author> <date>n.d.</date> </front> </reference> <reference anchor="IANA-YANG-PARAMETERS" target="https://www.iana.org/assignments/yang-parameters"> <front> <title>YANG Parameters</title> <author> <organization/> </author> <date>n.d.</date> </front> </reference> <reference anchor="IANA-TAGS" target="https://www.iana.org/assignments/yang-module-tags/"> <front> <title>YANG Module Tags</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="IANA_Tunnel_Type_URL" target="https://www.iana.org/assignments/iana-tunnel-type/iana-tunnel-type.xhtml"> <front> <title>iana-tunnel-type YANG Module</title> <author> <organization>IANA</organization> </author> <date/> </front> </reference> <reference anchor="ID-Guidelines" target="https://authors.ietf.org/en/content-guidelines-overview"> <front> <title>Guidelines to Authors of Internet-Drafts</title> <author> <organization>IETF</organization> </author> <date>n.d.</date> </front> </reference> <reference anchor="RFC8407"> <front> <title>Guidelines for Authors and Reviewers of Documents Containing YANG Data Models</title> <author fullname="A. Bierman" initials="A." surname="Bierman"/> <date month="October" year="2018"/> <abstract> <t>This memo provides guidelines for authors and reviewers of specifications containing YANG modules. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) and RESTCONF protocol implementations that utilize YANG modules. This document obsoletes RFC 6087.</t> </abstract> </front> <seriesInfo name="BCP" value="216"/> <seriesInfo name="RFC" value="8407"/> <seriesInfo name="DOI" value="10.17487/RFC8407"/> </reference> <reference anchor="RFC8675"> <front> <title>A YANG Data Model for Tunnel Interface Types</title> <author fullname="M. Boucadair" initials="M." surname="Boucadair"/> <author fullname="I. Farrer" initials="I." surname="Farrer"/> <author fullname="R. Asati" initials="R." surname="Asati"/> <date month="November" year="2019"/> <abstract> <t>This document specifies the initial version of a YANG module "iana-tunnel-type", whichcontainsa collection of IANA-maintained YANG identities used as interface types for tunnel interfaces. The module reflects the "tunnelType" registry maintained by IANA. The latest revision of this YANG module can be obtained from the IANA website.</t> <t>Tunnel type values are not directly added to the Tunnel Interface Types YANG module; they must instead be added to the "tunnelType" IANA registry. Once a new tunnel type registration is made by IANA for a new tunneling scheme or even an existing one that is not already listed in the current registry (e.g., LISP, NSH), IANA will update the Tunnel Interface Types YANG module accordingly.</t> <t>Some of the IETF-defined tunneling techniques are not listed in the current IANA registry. It is not the intent of this document to update the existing IANA registry with a comprehensive list of tunnel technologies. Registrants must follow the IETF registration procedure for interface types whenever a new tunnel type is needed.</t> </abstract> </front> <seriesInfo name="RFC" value="8675"/> <seriesInfo name="DOI" value="10.17487/RFC8675"/> </reference> <reference anchor="RFC9291"> <front> <title>A YANG Network Data Model for Layer 2 VPNs</title> <author fullname="M. Boucadair" initials="M." role="editor" surname="Boucadair"/> <author fullname="O. Gonzalez de Dios" initials="O." role="editor" surname="Gonzalez de Dios"/> <author fullname="S. Barguil" initials="S." surname="Barguil"/> <author fullname="L. Munoz" initials="L." surname="Munoz"/> <date month="September" year="2022"/> <abstract> <t>This document defines an L2VPN Network Model (L2NM) that can be used to manage the provisioning of Layer 2 Virtual Private Network (L2VPN) services within a network (e.g., a service provider network). The L2NM complements the L2VPN Service Model (L2SM) by providing a network-centric view of the service that is internal to a service provider. The L2NM is particularly meant to be used by a network controller to derive the configuration information that will be sent to relevant network devices.</t> <t>Also, this document defines a YANG module to manage Ethernet segments and the initial versions of two IANA-maintained modules that include a set of identities of BGP Layer 2 encapsulation types and pseudowire types.</t> </abstract> </front> <seriesInfo name="RFC" value="9291"/> <seriesInfo name="DOI" value="10.17487/RFC9291"/> </reference> <reference anchor="RFC2026"> <front> <title>The Internet Standards Process -- Revision 3</title> <author fullname="S. Bradner" initials="S." surname="Bradner"/> <date month="October" year="1996"/> <abstract> <t>This memo documents the process used by the Internet community for the standardization of protocols and procedures. It defines the stages in the standardization process, the requirements for moving a document between stages and the types of documents used during this process. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t> </abstract> </front> <seriesInfo name="BCP" value="9"/> <seriesInfo name="RFC" value="2026"/> <seriesInfo name="DOI" value="10.17487/RFC2026"/> </reference> <reference anchor="RFC8340"> <front> <title>YANG Tree Diagrams</title> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <author fullname="L. Berger" initials="L." role="editor" surname="Berger"/> <date month="March" year="2018"/> <abstract> <t>This document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language.</t> </abstract> </front> <seriesInfo name="BCP" value="215"/> <seriesInfo name="RFC" value="8340"/> <seriesInfo name="DOI" value="10.17487/RFC8340"/> </reference> <reference anchor="RFC8309"> <front> <title>Service Models Explained</title> <author fullname="Q. Wu" initials="Q." surname="Wu"/> <author fullname="W. Liu" initials="W." surname="Liu"/> <author fullname="A. Farrel" initials="A." surname="Farrel"/> <date month="January" year="2018"/> <abstract> <t>The IETF has produced many modules in the YANG modeling language. The majority of these modules are used to construct data models to model devices or monolithic functions.</t> <t>A small number of YANG modules have been defined to model services (for example, the Layer 3 Virtual Private Network Service Model (L3SM) produced by the L3SM working group and documented in RFC 8049).</t> <t>This document describes service models as used within the IETF and also shows where a service model might fit into a software-defined networking architecture. Note that service models do not make any assumption of how a service is actually engineered and delivered for a customer; details of how network protocols and devices are engineered to deliver a service are captured in other modules that are not exposed through the interface between the customer and the provider.</t> </abstract> </front> <seriesInfo name="RFC" value="8309"/> <seriesInfo name="DOI" value="10.17487/RFC8309"/> </reference> <reference anchor="RFC9129"> <front> <title>YANG Data Model for the OSPF Protocol</title> <author fullname="D. Yeung" initials="D." surname="Yeung"/> <author fullname="Y. Qu" initials="Y." surname="Qu"/> <author fullname="Z. Zhang" initials="Z." surname="Zhang"/> <author fullname="I. Chen" initials="I." surname="Chen"/> <author fullname="A. Lindem" initials="A." surname="Lindem"/> <date month="October" year="2022"/> <abstract> <t>This document defines a YANG data model that can be used to configure and manage OSPF. The model is based on YANG 1.1 as defined in RFC 7950 and conforms to the Network Management Datastore Architecture (NMDA) as described in RFC 8342.</t> </abstract> </front> <seriesInfo name="RFC" value="9129"/> <seriesInfo name="DOI" value="10.17487/RFC9129"/> </reference> <reference anchor="RFC7407"> <front> <title>A YANG Data Model for SNMP Configuration</title> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <author fullname="J. Schoenwaelder" initials="J." surname="Schoenwaelder"/> <date month="December" year="2014"/> <abstract> <t>This document defines a collection of YANG definitions for configuring SNMP engines.</t> </abstract> </front> <seriesInfo name="RFC" value="7407"/> <seriesInfo name="DOI" value="10.17487/RFC7407"/> </reference> <reference anchor="RFC8349"> <front> <title>A YANG Data Model for Routing Management (NMDA Version)</title> <author fullname="L. Lhotka" initials="L." surname="Lhotka"/> <author fullname="A. Lindem" initials="A." surname="Lindem"/> <author fullname="Y. Qu" initials="Y." surname="Qu"/> <date month="March" year="2018"/> <abstract> <t>This document specifies three YANG modules and one submodule. Together, they form the core routing data model that serves as a framework for configuring and managing a routing subsystem. It is expected that these modules will be augmented by additional YANG modules defining data models for control-plane protocols, route filters, and other functions. The core routing data model provides common building blocks for such extensions -- routes, Routing Information Bases (RIBs), and control-plane protocols.</t> <t>The YANG modules in this document conform totheNetwork Management Datastore Architecture (NMDA). This document obsoletes RFC 8022.</t> </abstract> </front> <seriesInfo name="RFC" value="8349"/> <seriesInfo name="DOI" value="10.17487/RFC8349"/> </reference> <reference anchor="RFC6991"> <front> <title>Common YANG Data Types</title> <author fullname="J. Schoenwaelder" initials="J." role="editor" surname="Schoenwaelder"/> <date month="July" year="2013"/> <abstract> <t>This document introduces a collection of common data types to be used with the YANG data modeling language. This document obsoletes RFC 6021.</t> </abstract> </front> <seriesInfo name="RFC" value="6991"/> <seriesInfo name="DOI" value="10.17487/RFC6991"/> </reference> <reference anchor="RFC8969"> <front> <title>A Framework for Automating Service and Network Management with YANG</title> <author fullname="Q. Wu" initials="Q." role="editor" surname="Wu"/> <author fullname="M. Boucadair" initials="M." role="editor" surname="Boucadair"/> <author fullname="D. Lopez" initials="D." surname="Lopez"/> <author fullname="C. Xie" initials="C." surname="Xie"/> <author fullname="L. Geng" initials="L." surname="Geng"/> <date month="January" year="2021"/> <abstract> <t>Data models provide a programmatic approach to represent services and networks. Concretely, they can be used to derive configuration information for network and service components, and state information that will be monitored and tracked. Data models can be used during the service and network management life cycle (e.g., service instantiation, service provisioning, service optimization, service monitoring, service diagnosing, and service assurance). Data models are also instrumental in the automation of network management, and they can provide closed-loop control for adaptive and deterministic service creation, delivery, and maintenance.</t> <t>This document describes a framework for service and network management automation that takes advantage of YANG modeling technologies. This framework is drawn from a network operator perspective irrespective of the origin of a data model; thus, it can accommodate YANG modules that are developed outside the IETF.</t> </abstract> </front> <seriesInfo name="RFC" value="8969"/> <seriesInfo name="DOI" value="10.17487/RFC8969"/> </reference> <reference anchor="RFC8299"> <front> <title>YANG Data Model for L3VPN Service Delivery</title> <author fullname="Q. Wu" initials="Q." role="editor" surname="Wu"/> <author fullname="S. Litkowski" initials="S." surname="Litkowski"/> <author fullname="L. Tomotaki" initials="L." surname="Tomotaki"/> <author fullname="K. Ogaki" initials="K." surname="Ogaki"/> <date month="January" year="2018"/> <abstract> <t>This document defines a YANG data model that can be used for communication between customers and network operators and to deliver a Layer 3 provider-provisioned VPN service. This document is limited to BGP PE-based VPNs as described in RFCs 4026, 4110, and 4364. This model is intended to be instantiated at the management system to deliver the overall service. It is not a configuration model to be used directly on network elements. This model provides an abstracted view of the Layer 3 IP VPN service configuration components. It will be up to the management system to take this model as input and use specific configuration models to configure the different network elements to deliver the service. How the configuration of network elements is done is out of scope for this document.</t> <t>This document obsoletes RFC 8049; it replaces the unimplementable module in that RFC with a new module with the same name that is not backward compatible. The changes are a series of small fixes to the YANG module and some clarifications torequired I-D boilerplate (see <https://www.ietf.org/id-info/ guidelines.html>), including thetext.</t> </abstract> </front> <seriesInfo name="RFC" value="8299"/> <seriesInfo name="DOI" value="10.17487/RFC8299"/> </reference> <reference anchor="RFC8466"> <front> <title>A YANG Data Model for Layer 2 Virtual Private Network (L2VPN) Service Delivery</title> <author fullname="B. Wen" initials="B." surname="Wen"/> <author fullname="G. Fioccola" initials="G." role="editor" surname="Fioccola"/> <author fullname="C. Xie" initials="C." surname="Xie"/> <author fullname="L. Jalil" initials="L." surname="Jalil"/> <date month="October" year="2018"/> <abstract> <t>This document defines a YANG data model that can be used to configure a Layer 2 provider-provisioned VPN service. It is up to a management systemappropriate statement totake thispermit publication as aninput and generate specific configuration models to configure the different network elements to deliver the service. How this configuration of network elements is done is out of scope for this document.</t> <t>The YANG data model defined in this document includes support for point-to-point Virtual Private Wire Services (VPWSs) and multipoint Virtual Private LAN Services (VPLSs) that use Pseudowires signaled using the Label Distribution Protocol (LDP) and the Border Gateway Protocol (BGP) as described in RFCs 4761 and 6624.</t> <t>The YANG data model defined in this document conforms to the Network Management Datastore Architecture defined in RFC 8342.</t> </abstract> </front> <seriesInfo name="RFC" value="8466"/> <seriesInfo name="DOI" value="10.17487/RFC8466"/> </reference> <reference anchor="RFC9182"> <front> <title>A YANG Network Data Model for Layer 3 VPNs</title> <author fullname="S. Barguil" initials="S." surname="Barguil"/> <author fullname="O. Gonzalez de Dios" initials="O." role="editor" surname="Gonzalez de Dios"/> <author fullname="M. Boucadair" initials="M." role="editor" surname="Boucadair"/> <author fullname="L. Munoz" initials="L." surname="Munoz"/> <author fullname="A. Aguado" initials="A." surname="Aguado"/> <date month="February" year="2022"/> <abstract> <t>As a complement to the Layer 3 Virtual Private Network Service Model (L3SM), which is used for communication between customers and service providers, this document defines an L3VPN Network Model (L3NM) that can be used for the provisioning of Layer 3 Virtual Private Network (L3VPN) services within a service provider network. The model provides a network-centric view of L3VPN services.</t> <t>The L3NM is meant to be used by a network controller to derive the configuration information that will be sent to relevant network devices. The model can also facilitate communication between a service orchestrator and a network controller/orchestrator.</t> </abstract> </front> <seriesInfo name="RFC" value="9182"/> <seriesInfo name="DOI" value="10.17487/RFC9182"/> </reference> <reference anchor="RFC8199"> <front> <title>YANG Module Classification</title> <author fullname="D. Bogdanovic" initials="D." surname="Bogdanovic"/> <author fullname="B. Claise" initials="B." surname="Claise"/> <author fullname="C. Moberg" initials="C." surname="Moberg"/> <date month="July" year="2017"/> <abstract> <t>The YANG data modeling language is currently being considered for a wide variety of applications throughout the networking industry at large. Many standards development organizations (SDOs), open-source software projects, vendors, and users are using YANG to develop and publish YANG modules for a wide variety of applications. At the same time, there is currently no well-known terminology to categorize various types of YANG modules.</t> <t>A consistent terminology would help with the categorization of YANG modules, assist in the analysis of the YANG data modeling efforts in the IETF and other organizations, and bring clarity to the YANG- related discussions between the different groups.</t> <t>This document describes a set of concepts and associated terms to support consistent classification of YANG modules.</t> </abstract> </front> <seriesInfo name="RFC" value="8199"/> <seriesInfo name="DOI" value="10.17487/RFC8199"/> </reference> <reference anchor="RFC8519"> <front> <title>YANG Data Model for Network Access Control Lists (ACLs)</title> <author fullname="M. Jethanandani" initials="M." surname="Jethanandani"/> <author fullname="S. Agarwal" initials="S." surname="Agarwal"/> <author fullname="L. Huang" initials="L." surname="Huang"/> <author fullname="D. Blair" initials="D." surname="Blair"/> <date month="March" year="2019"/> <abstract> <t>This document defines a data model for Access Control Lists (ACLs). An ACL is a user-ordered set of rules used to configure the forwarding behavior in a device. Each rule is used to find a match on a packet and define actions that will be performed on the packet.</t> </abstract> </front> <seriesInfo name="RFC" value="8519"/> <seriesInfo name="DOI" value="10.17487/RFC8519"/> </reference> <reference anchor="RFC4252"> <front> <title>The Secure Shell (SSH) Authentication Protocol</title> <author fullname="T. Ylonen" initials="T." surname="Ylonen"/> <author fullname="C. Lonvick" initials="C." role="editor" surname="Lonvick"/> <date month="January" year="2006"/> <abstract> <t>The Secure Shell Protocol (SSH) is a protocol for secure remote login and other secure network services over an insecure network. This document describes the SSH authentication protocol framework and public key, password, and host-based client authentication methods. Additional authentication methods are described in separate documents. The SSH authentication protocol runs on top of the SSH transport layer protocol and provides a single authenticated tunnel for the SSH connection protocol. [STANDARDS-TRACK]</t> </abstract> </front> <seriesInfo name="RFC" value="4252"/> <seriesInfo name="DOI" value="10.17487/RFC4252"/> </reference> <reference anchor="RFC8446"> <front> <title>The Transport Layer Security (TLS) Protocol Version 1.3</title> <author fullname="E. Rescorla" initials="E." surname="Rescorla"/> <date month="August" year="2018"/> <abstract> <t>This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery.</t> <t>This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations.</t> </abstract> </front> <seriesInfo name="RFC" value="8446"/> <seriesInfo name="DOI" value="10.17487/RFC8446"/> </reference> <reference anchor="RFC9000"> <front> <title>QUIC: A UDP-Based Multiplexed and Secure Transport</title> <author fullname="J. Iyengar" initials="J." role="editor" surname="Iyengar"/> <author fullname="M. Thomson" initials="M." role="editor" surname="Thomson"/> <date month="May" year="2021"/> <abstract> <t>This document defines the core of the QUIC transport protocol. QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment,RFC, andnetwork path migration. QUIC includes security measuresthatensure confidentiality, integrity, and availability in a range of deployment circumstances. Accompanying documents describe the integration of TLS for key negotiation, loss detection, and an exemplary congestion control algorithm.</t> </abstract> </front> <seriesInfo name="RFC" value="9000"/> <seriesInfo name="DOI" value="10.17487/RFC9000"/> </reference> <reference anchor="RFC7951"> <front> <title>JSON Encoding of Data Modeled with YANG</title> <author fullname="L. Lhotka" initials="L." surname="Lhotka"/> <date month="August" year="2016"/> <abstract> <t>This document defines encoding rules for representing configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text.</t> </abstract> </front> <seriesInfo name="RFC" value="7951"/> <seriesInfo name="DOI" value="10.17487/RFC7951"/> </reference> <reference anchor="RFC5737"> <front> <title>IPv4 Address Blocks Reserved for Documentation</title> <author fullname="J. Arkko" initials="J." surname="Arkko"/> <author fullname="M. Cotton" initials="M." surname="Cotton"/> <author fullname="L. Vegoda" initials="L." surname="Vegoda"/> <date month="January" year="2010"/> <abstract> <t>Three IPv4 unicast address blocks are reserved for use in examples in specifications and other documents. This document describestheuse of these blocks. This document isI-D boilerplate does notan Internet Standards Track specification; it is published for informational purposes.</t> </abstract> </front> <seriesInfo name="RFC" value="5737"/> <seriesInfo name="DOI" value="10.17487/RFC5737"/> </reference> <reference anchor="RFC3849"> <front> <title>IPv6 Address Prefix Reserved for Documentation</title> <author fullname="G. Huston" initials="G." surname="Huston"/> <author fullname="A. Lord" initials="A." surname="Lord"/> <author fullname="P. Smith" initials="P." surname="Smith"/> <date month="July" year="2004"/> <abstract> <t>To reduce the likelihood of conflict and confusion when relating documented examples to deployed systems, an IPv6 unicast address prefix is reserved for use in examples in RFCs, books, documentation, and the like. Since site-local and link-local unicast addresses have special meaning in IPv6, these addresses cannot be used in many example situations. The document describes the use of the IPv6 address prefix 2001:DB8::/32 as a reserved prefix for use in documentation. This memo provides information for the Internet community.</t> </abstract> </front> <seriesInfo name="RFC" value="3849"/> <seriesInfo name="DOI" value="10.17487/RFC3849"/> </reference> <reference anchor="RFC9637"> <front> <title>Expanding the IPv6 Documentation Space</title> <author fullname="G. Huston" initials="G." surname="Huston"/> <author fullname="N. Buraglio" initials="N." surname="Buraglio"/> <date month="August" year="2024"/> <abstract> <t>The document describes the reservation of an additional IPv6 address prefix for use in documentation. This update to RFC 3849 expands on the existing 2001:db8::/32 address block with the reservation of an additional, larger prefix. The addition of a /20 prefix allows documented examples to more closely reflect a broader range of realistic, current deployment scenarios and more closely aligns with contemporary allocation models for large networks.</t> </abstract> </front> <seriesInfo name="RFC" value="9637"/> <seriesInfo name="DOI" value="10.17487/RFC9637"/> </reference> <reference anchor="RFC5612"> <front> <title>Enterprise Number for Documentation Use</title> <author fullname="P. Eronen" initials="P." surname="Eronen"/> <author fullname="D. Harrington" initials="D." surname="Harrington"/> <date month="August" year="2009"/> <abstract> <t>This document describes an Enterprise Number (also known as SMI Network Management Private Enterprise Code) for use in documentation. This memo provides information for the Internet community.</t> </abstract> </front> <seriesInfo name="RFC" value="5612"/> <seriesInfo name="DOI" value="10.17487/RFC5612"/> </reference> <reference anchor="RFC5398"> <front> <title>Autonomous System (AS) Number Reservation for Documentation Use</title> <author fullname="G. Huston" initials="G." surname="Huston"/> <date month="December" year="2008"/> <abstract> <t>To reduce the likelihood of conflict and confusion when relating documented examples to deployed systems, two blocks of Autonomous System numbers (ASNs) are reserved for use in examples in RFCs, books, documentation, and the like. This document describes the reservation of two blocks of ASNs as reserved numbers for use in documentation. This memo provides information for the Internet community.</t> </abstract> </front> <seriesInfo name="RFC" value="5398"/> <seriesInfo name="DOI" value="10.17487/RFC5398"/> </reference> <reference anchor="RFC2606"> <front> <title>Reserved Top Level DNS Names</title> <author fullname="D. Eastlake 3rd" initials="D." surname="Eastlake 3rd"/> <author fullname="A. Panitz" initials="A." surname="Panitz"/> <date month="June" year="1999"/> <abstract> <t>To reduce the likelihood of conflict and confusion, a few top level domain names are reserved for use in private testing, as examples in documentation, and the like. In addition, a few second level domain names reserved for use as examples are documented. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t> </abstract> </front> <seriesInfo name="BCP" value="32"/> <seriesInfo name="RFC" value="2606"/> <seriesInfo name="DOI" value="10.17487/RFC2606"/> </reference> <reference anchor="RFC4151"> <front> <title>The 'tag' URI Scheme</title> <author fullname="T. Kindberg" initials="T." surname="Kindberg"/> <author fullname="S. Hawke" initials="S." surname="Hawke"/> <date month="October" year="2005"/> <abstract> <t>This document describes the "tag" Uniform Resource Identifier (URI) scheme. Tag URIs (also known as "tags") are designed to be unique across space and time while being tractable to humans. They are distinct from most other URIs in that they have no authoritative resolution mechanism. A tag may be used purely as an entity identifier. Furthermore, using tags has some advantages over the common practice of using "http" URIs as identifiers for non-HTTP-accessible resources. This memo provides information for the Internet community.</t> </abstract> </front> <seriesInfo name="RFC" value="4151"/> <seriesInfo name="DOI" value="10.17487/RFC4151"/> </reference> <reference anchor="RFC8343"> <front> <title>A YANG Data Model for Interface Management</title> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <date month="March" year="2018"/> <abstract> <t>This document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes definitions for configuration and system state (status information and counters for the collection of statistics).</t> <t>The YANG data model in this document conforms to the Network Management Datastore Architecture (NMDA) defined in RFC 8342.</t> <t>This document obsoletes RFC 7223.</t> </abstract> </front> <seriesInfo name="RFC" value="8343"/> <seriesInfo name="DOI" value="10.17487/RFC8343"/> </reference> <reference anchor="RFC7223"> <front> <title>A YANG Data Model for Interface Management</title> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <date month="May" year="2014"/> <abstract> <t>This document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes configuration data and state data (status information and counters for the collection of statistics).</t> </abstract> </front> <seriesInfo name="RFC" value="7223"/> <seriesInfo name="DOI" value="10.17487/RFC7223"/> </reference> <reference anchor="RFC9132"> <front> <title>Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Specification</title> <author fullname="M. Boucadair" initials="M." role="editor" surname="Boucadair"/> <author fullname="J. Shallow" initials="J." surname="Shallow"/> <author fullname="T. Reddy.K" initials="T." surname="Reddy.K"/> <date month="September" year="2021"/> <abstract> <t>This document specifies the Distributed Denial-of-Service Open Threat Signaling (DOTS) signal channel, a protocol for signaling the need for protection against Distributed Denial-of-Service (DDoS) attacks to a server capable of enabling network traffic mitigation on behalf of the requesting client.</t> <t>A companion document defines the DOTS data channel, a separate reliable communication layer for DOTS management and configuration purposes.</t> <t>This document obsoletes RFC 8782.</t> </abstract> </front> <seriesInfo name="RFC" value="9132"/> <seriesInfo name="DOI" value="10.17487/RFC9132"/> </reference> <reference anchor="RFC9195"> <front> <title>A File Format for YANG Instance Data</title> <author fullname="B. Lengyel" initials="B." surname="Lengyel"/> <author fullname="B. Claise" initials="B." surname="Claise"/> <date month="February" year="2022"/> <abstract> <t>There is a need to document data defined in YANG models at design time, implementation time,contain references orwhen a live server is unavailable. This document specifies a standard file format for YANG instance data, which follows the syntax and semantics of existing YANG models and annotates it with metadata.</t> </abstract> </front> <seriesInfo name="RFC" value="9195"/> <seriesInfo name="DOI" value="10.17487/RFC9195"/> </reference> <reference anchor="RFC9244"> <front> <title>Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry</title> <author fullname="M. Boucadair" initials="M." role="editor" surname="Boucadair"/> <author fullname="T. Reddy.K" initials="T." role="editor" surname="Reddy.K"/> <author fullname="E. Doron" initials="E." surname="Doron"/> <author fullname="M. Chen" initials="M." surname="Chen"/> <author fullname="J. Shallow" initials="J." surname="Shallow"/> <date month="June" year="2022"/> <abstract> <t>This document aims to enrich the Distributed Denial-of-Service Open Threat Signaling (DOTS) signal channel protocol with various telemetry attributes, allowing for optimal Distributed Denial-of-Service (DDoS) attack mitigation. It specifies the normal traffic baseline and attack traffic telemetry attributes a DOTS client can convey to its DOTS server in the mitigation request, the mitigation status telemetry attributes a DOTS server can communicate to a DOTS client, and the mitigation efficacy telemetry attributes a DOTS client can communicate to a DOTS server. The telemetry attributes can assist the mitigator in choosing the DDoS mitigation techniques and performing optimal DDoS attack mitigation.</t> <t>This document specifies two YANG modules: one for representing DOTS telemetry message types and one for sharing the attack mapping details over the DOTS data channel.</t> </abstract> </front> <seriesInfo name="RFC" value="9244"/> <seriesInfo name="DOI" value="10.17487/RFC9244"/> </reference> <reference anchor="RFC9362"> <front> <title>Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Configuration Attributes for Robust Block Transmission</title> <author fullname="M. Boucadair" initials="M." surname="Boucadair"/> <author fullname="J. Shallow" initials="J." surname="Shallow"/> <date month="February" year="2023"/> <abstract> <t>This document specifies new DDoS Open Threat Signaling (DOTS) signal channel configuration parameterssection numbers. Perhaps: * I-D Boilerplate: Verify thatcan be negotiated between DOTS peers to enabletheuse of Q-Block1 and Q-Block2 Constrained Application Protocol (CoAP) options. These options enable robust and faster transmission rates for large amounts of data with less packet interchanges as well as support for faster recovery should any of the blocks get lost in transmission (especially during DDoS attacks).</t> <t>Also, this document defines a YANG data model for representing these new DOTS signal channel configuration parameters. This model augments the DOTS signal YANG module ("ietf-dots-signal-channel") defined in RFC 9132.</t> </abstract> </front> <seriesInfo name="RFC" value="9362"/> <seriesInfo name="DOI" value="10.17487/RFC9362"/> </reference> <reference anchor="RFC8892"> <front> <title>Guidelines and Registration Procedures for Interface Types and Tunnel Types</title> <author fullname="D. Thaler" initials="D." surname="Thaler"/> <author fullname="D. Romascanu" initials="D." surname="Romascanu"/> <date month="August" year="2020"/> <abstract> <t>This document provides guidelines and procedures for those who are defining, registering, or evaluating definitions of new interface types ("ifType" values) and tunnel types. The original definition of the IANA interface type registry predated the use of IANA Considerations sections and YANG modules, so some confusion arose over time. Tunnel types were added later, with the same requirements and allocation policy as interface types. This document updates RFC 2863 and provides updated guidance for these registries.</t> </abstract> </front> <seriesInfo name="RFC" value="8892"/> <seriesInfo name="DOI" value="10.17487/RFC8892"/> </reference> <reference anchor="RFC2863"> <front> <title>The Interfaces Group MIB</title> <author fullname="K. McCloghrie" initials="K." surname="McCloghrie"/> <author fullname="F. Kastenholz" initials="F." surname="Kastenholz"/> <date month="June" year="2000"/> <abstract> <t>This memo discusses the 'interfaces' group of MIB-II, especially the experience gained from the definition of numerous media-specific MIB modules for use in conjunction with the 'interfaces' group for managing various sub-layers beneath the internetwork-layer. It specifies clarifications to, and extensions of, the architectural issues within the MIB-II model of the 'interfaces' group. [STANDARDS-TRACK]</t> </abstract> </front> <seriesInfo name="RFC" value="2863"/> <seriesInfo name="DOI" value="10.17487/RFC2863"/> </reference> <reference anchor="RFC7224"> <front> <title>IANA Interface Type YANG Module</title> <author fullname="M. Bjorklund" initials="M." surname="Bjorklund"/> <date month="May" year="2014"/> <abstract> <t>This document defines the initial version of the iana-if-type YANG module.</t> </abstract> </front> <seriesInfo name="RFC" value="7224"/> <seriesInfo name="DOI" value="10.17487/RFC7224"/> </reference> <reference anchor="RFC9108"> <front> <title>YANG Types for DNS Classes and Resource Record Types</title> <author fullname="L. Lhotka" initials="L." surname="Lhotka"/> <author fullname="P. Špaček" initials="P." surname="Špaček"/> <date month="September" year="2021"/> <abstract> <t>Thisdocumentintroduces the YANG module "iana-dns-class-rr-type", whichcontainsderived types reflecting two IANA registries: DNS CLASSes and Resource Record (RR) TYPEs. These YANG types are intended astheminimum basis for future data modeling work.</t> </abstract> </front> <seriesInfo name="RFC" value="9108"/> <seriesInfo name="DOI" value="10.17487/RFC9108"/> </reference> <reference anchor="RFC9645"> <front> <title>YANG Groupings for TLS Clients and TLS Servers</title> <author fullname="K. Watsen" initials="K." surname="Watsen"/> <date month="October" year="2024"/> <abstract> <t>This document presents four YANG 1.1 modules -- three IETF modules and one supporting IANA module.</t> <t>The three IETF modules are "ietf-tls-common", "ietf-tls-client", and "ietf-tls-server". The "ietf-tls-client" and "ietf-tls-server" modules are the primary productions of this work, supporting the configuration and monitoring of TLS clients and servers.</t> <t>The IANA module is "iana-tls-cipher-suite-algs". This module defines YANG enumerations that provide support for an IANA-maintained algorithm registry.</t> </abstract> </front> <seriesInfo name="RFC" value="9645"/> <seriesInfo name="DOI" value="10.17487/RFC9645"/> </reference> <reference anchor="RFC4253"> <front> <title>The Secure Shell (SSH) Transport Layer Protocol</title> <author fullname="T. Ylonen" initials="T." surname="Ylonen"/> <author fullname="C. Lonvick" initials="C." role="editor" surname="Lonvick"/> <date month="January" year="2006"/> <abstract> <t>The Secure Shell (SSH) is a protocol for secure remote login and other secure network services over an insecure network.</t> <t>This document describes the SSH transport layer protocol, which typically runs on top of TCP/IP. The protocol can be used as a basis for a number of secure network services. It provides strong encryption, server authentication, and integrity protection. It may also provide compression.</t> <t>Key exchange method, public key algorithm, symmetric encryption algorithm, message authentication algorithm, and hash algorithm are all negotiated.</t> <t>This document also describes the Diffie-Hellman key exchange method and the minimal set of algorithms that are needed to implement the SSH transport layer protocol. [STANDARDS-TRACK]</t> </abstract> </front> <seriesInfo name="RFC" value="4253"/> <seriesInfo name="DOI" value="10.17487/RFC4253"/> </reference> <reference anchor="RFC4181"> <front> <title>Guidelines for Authors and Reviewers of MIB Documents</title> <author fullname="C. Heard" initials="C." role="editor" surname="Heard"/> <date month="September" year="2005"/> <abstract> <t>This memo provides guidelines for authors and reviewers of IETF standards-track specifications containing MIB modules. Applicable portions may be used as a basis for reviews of other MIB documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t> </abstract> </front> <seriesInfo name="BCP" value="111"/> <seriesInfo name="RFC" value="4181"/> <seriesInfo name="DOI" value="10.17487/RFC4181"/> </reference> </references> </references> <?line 3487?> <section anchor="module-review-checklist"> <name>Module Review Checklist</name> <t>This section is adapted from <xref target="RFC4181"/>.</t>required sections (see <https://authors.ietf.org/required-content>). --> <t>The purpose of a YANG module review is to review the YANG module for both technical correctness and adherence to IETF documentation requirements. The following checklist may be helpful when reviewing an I-D:</t> <ul spacing="normal"> <li> <t>I-DBoilerplate -- verifyBoilerplate: Verify that the document contains the required I-D boilerplate (see<tt><https://www.ietf.org/id-info/guidelines.html></tt>),<eref target="https://www.ietf.org/id-info/guidelines.html" brackets="angle"/>), including the appropriate statement to permit publication as an RFC, and that the I-D boilerplate does not contain references or section numbers.</t> </li> <li><t>Abstract -- verify<t>Abstract: Verify that the abstract does not contain references, that it does not have a section number, and that its content follows the guidelines in<tt><https://www.ietf.org/id-info/guidelines.html></tt>.</t><eref target="https://www.ietf.org/id-info/guidelines.html" brackets="angle"/>.</t> </li> <li> <t>CopyrightNotice -- verifyNotice: Verify that the document has the appropriate text regarding the rights that document contributors provide to the IETF Trust <xref target="RFC5378"/>. Verify that it contains the full IETF Trust copyright notice at the beginning of the document. The IETF Trust Legal Provisions (TLP) can be found at:</t> <t><tt><https://trustee.ietf.org/license-info/></tt></t><eref target="https://trustee.ietf.org/license-info/" brackets="angle"/></t> </li> <li> <t>Security Considerationssection --section: If none of the modules in the document falls under the exceptions in <xref target="sec-sec-cons-sec"/> (e.g., use YANG data structure), verify that the section is modeled after the latest approved template from the Operations and Management (OPS) area website (see<tt><https://wiki.ietf.org/group/ops/yang-security-guidelines></tt>)<eref target="https://wiki.ietf.org/group/ops/yang-security-guidelines" brackets="angle"/>) and that the guidelines therein have been followed.</t> </li> <li> <t>IANA Considerationssection -- thissection: This section must always be present. For each module within the document, ensure that the IANA Considerations section contains entries for the following IANA registries: </t><dl> <dt>XML<ul> <li>XML NamespaceRegistry:</dt> <dd> <t>RegisterRegistry: Register the YANG modulenamespace.</t> </dd> <dt>YANGnamespace.</li> <li>YANG ModuleRegistry:</dt> <dd> <t>RegisterRegistry: Register the YANG module name, prefix, namespace, and RFCnumber,number according to the rules specified in <xreftarget="RFC6020"/>.</t> </dd> </dl>target="RFC6020"/>.</li> </ul> </li> <li><t>References -- verify<t>References: Verify that the references are properly divided between normative and informative references, that RFCs 2119 and 8174 are included as normative references if the terminology defined therein is used in the document, that all references required by the boilerplate are present, that all YANG modules containing imported items are cited as normative references, and that all citations point to the most current RFCs, unless there is a valid reason to do otherwise (for example, it is okay to include an informative reference to a previous version of a specification to help explain a feature included for backward compatibility). Be sure citations for all imported modules are present somewhere in the document text (outside the YANG module). If a YANG module containsreference"reference" or "description" statements that refer to an I-D, then the I-D is included as an informative reference.</t> </li> <li><t>License -- verify<t>License: Verify that the document contains the Revised BSD License in each YANG module or submodule. Some guidelines related to this requirement are described inSection 3.1.<xref target="module-copyright"/>. Make sure that the correct year is used in all copyright dates. Use the approved text from the latest TLP document, which can be found at:</t> <t><tt><https://trustee.ietf.org/license-info/></tt></t><eref target="https://trustee.ietf.org/license-info/" brackets="angle"/></t> </li> <li> <t>OtherIssues -- checkIssues: Check for any issues mentioned in<tt><https://www.ietf.org/id-info/checklist.html></tt><eref target="https://www.ietf.org/id-info/checklist.html" brackets="angle"/> that are not covered elsewhere.</t> </li> <li> <t>TechnicalContent -- reviewContent: Review the actual technical content for compliance with the guidelines in this document. The use of a YANG module compiler is recommended when checking for syntax errors. A list of freely available tools and other information, including formatting advice, can be found at:</t> <t><tt><https://wiki.ietf.org/group/netconf></tt> </t> <t><eref target="https://wiki.ietf.org/group/netconf" brackets="angle"/> and <eref target="https://wiki.ietf.org/group/netmod" brackets="angle"/> </t><t><tt><https://wiki.ietf.org/group/netmod></tt> </t> <t> Checking<t>Checking for correct syntax, however, is only part of the job. It is just as important to actually read the YANG module document from the point of view of a potential implementor. It is particularly important to check that "description" statements are sufficiently clear and unambiguous to allow interoperable implementations to be created.</t> </li> </ul> </section> <section anchor="tem-ietf"> <name>Template for IETF Modules</name> <!--[rfced] We assume these warnings and errors for the template modules are as expected (from pyang with the ietf option). Please let us know if any updates are needed. - Appendix B ietf-template@2023-07-26.yang:1: warning: unexpected latest revision "date-revision" in ietf-template@2023-07-26.yang, should be "2023-07-26" ietf-template@2023-07-26.yang:52: warning: RFC 8407: 3.1: The IETF Trust Copyright statement seems to be missing or is not correct (see pyang -ietf-help for details). ietf-template@2023-07-26.yang:60: error: bad value "date-revision" (should be date) ietf-template@2023-07-26.yang:71: error: bad value "date-initial" (should be date) - Appendix C iana-template@2023-12-08.yang:1: warning: unexpected latest revision "date-revision" in iana-template@2023-12-08.yang, should be "2023-12-08" iana-template@2023-12-08.yang:57: warning: RFC 8407: 3.1: The IETF Trust Copyright statement seems to be missing or is not correct (see pyang -ietf-help for details). iana-template@2023-12-08.yang:68: error: bad value "date-revision" (should be date) iana-template@2023-12-08.yang:80: error: bad value "date-initial" (should be date) --> <sourcecodemarkers="true" name="ietf-template@2023-07-26.yang"><![CDATA[name="ietf-template@2023-07-26.yang" type="yang" markers="true"><![CDATA[ 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: <http://datatracker.ietf.org/wg/your-wg-name/> WG List: <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 thisdocumentdocument. 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.: replaceXXXX/YYYYXXXX with actual RFC number and remove // this note // replace 'date-revision' with the module publication date // the format is (YYYY-MM-DD) revision date-revision { description "What changed in this revision."; reference "RFC XXXX: <Replace With Document 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 revision date-initial { description "Initialversion";version."; reference "RFCYYYY:XXXX: <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} ]]></sourcecode>}]]></sourcecode> </section> <section anchor="tem-iana"> <name>Template for IANA-Maintained Modules</name> <sourcecodemarkers="true" name="iana-template@2023-12-08.yang"><![CDATA[name="iana-template@2023-12-08.yang" markers="true"><![CDATA[ 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 424 254 5300 <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 ofRFCAAAA.";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 "Initialversion";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} ]]></sourcecode>}]]></sourcecode> </section> <section numbered="false" anchor="acknowledgments"> <name>Acknowledgments</name> <t>Thanks toJürgen Schönwälder and Ladislav Lhotka<contact fullname="Jürgen Schönwälder"/> and <contact fullname="Ladislav Lhotka"/> for the discussion and valuable comments. Special thanks toLadislav Lhotka<contact fullname="Ladislav Lhotka"/> for sharing more context that led to the design documented in <xref target="RFC9108"/>.</t> <t>Thanks toItalo Busi, Benoît Claise, Tom Petch, Randy Presuhn, Martin Björklund, Acee Lindem, Dale<contact fullname="Italo Busi"/>, <contact fullname="Benoît Claise"/>, <contact fullname="Tom Petch"/>, <contact fullname="Randy Presuhn"/>, <contact fullname="Martin Björklund"/>, <contact fullname="Acee Lindem"/>, <contact fullname="Dale R.Worley, Kent Watsen, Jan Lindblad, Qiufang Ma, Mahesh Jethanandani, Robert Wilton, and Thomas FossatiWorley"/>, <contact fullname="Kent Watsen"/>, <contact fullname="Jan Lindblad"/>, <contact fullname="Qiufang Ma"/>, <contact fullname="Mahesh Jethanandani"/>, <contact fullname="Robert Wilton"/>, and <contact fullname="Thomas Fossati"/> for the comments.</t><t>Lou Berger<t><contact fullname="Lou Berger"/> suggested to include more details about IANA considerations.</t> <t><xref target="sec-tags"/> is inspiredfromby <xref target="RFC8819"/>.</t><t>Michal Vaško<t><contact fullname="Michal Vaško"/> reported an inconsistency in Sections <xref target="RFC8407" section="4.6.2" sectionFormat="bare"/> and <xref target="RFC8407" section="4.6.4" sectionFormat="bare"/> of <xref target="RFC8407"/>.</t> <t>Thanks toXufeng Liu<contact fullname="Xufeng Liu"/> for reviewing the document, including providing YANGDOCTORS reviews.</t><t>Italo Busi<t><contact fullname="Italo Busi"/> provided the examples of "case + when" construct.</t> <t>Thanks toRich Salz and Michael Richardson<contact fullname="Rich Salz"/> and <contact fullname="Michael Richardson"/> for the SAAG review.</t><t>Kent Watsen<t><contact fullname="Kent Watsen"/> contributed text to the security and IANA-maintained module templates.</t> <t>Special thanks toAmanda Baber<contact fullname="Amanda Baber"/> for the thoughtful and careful review of the document.</t> <t>Thanks toQiufang Ma<contact fullname="Qiufang Ma"/> for the careful shepherd review.</t> <t>Thanks toAcee Lindem<contact fullname="Acee Lindem"/> for triggering the discussion on data modelvs.versus module.</t> <t>Thanks toMahesh Jethanandani<contact fullname="Mahesh Jethanandani"/> for the thoughtful AD review.</t> <t>Thanks toChrister Holmberg<contact fullname="Christer Holmberg"/> for the genart review,Jean Mahoney<contact fullname="Jean Mahoney"/> for the check on RPC implications,Ralf Weber<contact fullname="Ralf Weber"/> for the dnsdir,Giuseppe Fioccola<contact fullname="Giuseppe Fioccola"/> for the opsdir review,Joseph Touch<contact fullname="Joseph Touch"/> for the tsvart review, andYoav Nir<contact fullname="Yoav Nir"/> for the secdir review.</t> <t>ThanksÉric Vyncke, Mike Bishop, Roman Danyliw, Orie Steele, Ketan Talaulikar, Deb Cooley, and Gorry Fairhurst<contact fullname="Éric Vyncke"/>, <contact fullname="Mike Bishop"/>, <contact fullname="Roman Danyliw"/>, <contact fullname="Orie Steele"/>, <contact fullname="Ketan Talaulikar"/>, <contact fullname="Deb Cooley"/>, and <contact fullname="Gorry Fairhurst"/> for the IESG review.</t><dl> <dt>The<t>The author of RFC8407:</dt> <dd> <t>Andy Bierman</t> </dd> <dt/> <dd> <t>YumaWorks</t> </dd> <dt/> <dd> <t>email: andy@yumaworks.com</t> </dd> <dt>Acknowledgments8407:</t> <contact fullname="Andy Bierman"> <organization>YumaWorks</organization> <address> <email>andy@yumaworks.com</email> </address> </contact> <t>Acknowledgments from RFC8407:</dt> <dd> <t>The8407:</t> <blockquote><t>The structure and contents of this document are adapted from "Guidelines for Authors and Reviewers of MIB Documents" <xref target="RFC4181"/>, byC.<contact fullname="C. M.Heard.</t> </dd> <dt/> <dd>Heard"/>.</t> <t>The working group thanksMartin Bjorklund, Juergen Schoenwaelder, Ladislav Lhotka, Jernej Tuljak, Lou Berger, Robert Wilton, Kent Watsen, and William Lupton<contact fullname="Martin Bjorklund"/>, <contact fullname="Juergen Schoenwaelder"/>, <contact fullname="Ladislav Lhotka"/>, <contact fullname="Jernej Tuljak"/>, <contact fullname="Lou Berger"/>, <contact fullname="Robert Wilton"/>, <contact fullname="Kent Watsen"/>, and <contact fullname="William Lupton"/> for their extensive reviews and contributions to thisdocument.</t> </dd> </dl>document.</t></blockquote> </section></back><!--[rfced] We have the following questions related to terminology usage throughout the document. a) Should "IANA-maintained modules" be "IANA-maintained YANG modules"? We made this change in the Abstract and Intro already, but should this carry throughout the text? b) We note that <CODE BEGINS>, <CODE ENDS>, and some other bracketed terms (e.g., <b>) used in running text also appear in quotes (i.e., "<CODE BEGINS>") in some instances but simply bracketed in others (e.g., <get>). Please review and let us know if/how these may be made consistent. c) We note that templates in this document use a mix of filler numbers for RFCs (e.g., RFC IIII, RFC XXXX, FFFF). We suggest updating to use RFC XXXX throughout. Please let us know any objections. d) Please review the use of module/model when it appears without YANG and confirm that these instances appear as intended. For example, (a) uses "modules" and (b) uses "models" in the following: Original: (a) Modules that require immediate support for the NMDA features SHOULD be structured for NMDA. but then: ...as either an existing model or a model created by hand or with suitable tools that mirror the current modeling strategies. and: (b) For published models, the model should be republished with an NMDA-compatible structure, deprecating non-NMDA constructs. e) We note that there may be some inconsistency in the double quotes around statement names. For example, these terms are not quoted at places in the text: import statement include statement normative reference statement XPath statement extension statement YANG statement YANG extension statement YANG conditional statement reference statement length statement module tag extension statement Please review and let us know if/how these should be updated to fit with the other statement names (that are generally quoted). NOTE 1: We have added some quotes to "revision" statement. Please review and confirm these changes. NOTE 2: We see that the quotes around require-instance statement were removed between RFC 8407 and this document. Please review and confirm this update is as intended. NOTE 3: We sometimes see the use of YANG statement. Should these simply be statement? "when" statement vs. "when" YANG statement "must" statement vs. "must" YANG statement f) Further, there are some similar terms that may benefit from quotation review. We see: when expression vs. "when" expression must expression vs. "must" expression "enumeration" data type vs. enumeration data type vs. enumeration typedefs present vs. "not present" anyxml vs. "anyxml" descendant data nodes vs. "descendant" axis user-ordered list vs. user-ordered "list" leaf-list vs. "leaf-list" false vs. "false" true vs. "true" "deprecated" vs. "status deprecated" --> <!--##markdown-source: H4sIAAAAAAAAA+y9+3rbyJUv+j+eApv5zrbVISlLdrvb6suM2nZ3PMeWPbZ6 Otk9vWOQBCXEIMABQMlMx3mW8yznyU6ta60qgJTsZM5k72/7+5IWSaCuq1at 629NJpOkK7oyP0lHP2yKRV4WVd6my7pJTzfdZd20aVYt0tf5VZFf5+5TvUyf 1PPNKq+6Nn1cV11WVEV1kf7h9OyH9EnWZemL2rXSjpJsNmvyq3679KS0MUrm WZdf1M32JJ3N14n730l6fPQwqWdtXeZd3p6kXz6490WyWS8y+nR0/DBJFvW8 ylZu2IsmW3aTIu+WkyrvVvVi0izn8MasaCfHXybtZrYq2rZwQ92u3fPPnp5/ n1Sb1SxvThJo8iSZ11WbV+3GNd41mzxxg76fZE2eucG/XOdN1rm3aSFeZFV2 kcPIR8l13by7aOqNG/DoLO/gI03erccoeZdv3TeLkySdpGdPzx+/PPse/nz9 9I3+7Va4XmHjSdJ2rvk/ZmVduTFu8zZZFyfpz109H6dt3XRNvmzdX9sV/9E1 xbwbp/N6has4Tt16rLL12nX9S5JkuHXQdZK6f8tNWdJinVaLbfpdkTerrMKf 6uYiq4o/4yBO0j9sVtlPbhot/javN1UH+/Ljm1P8Il9lRXkC67D95617FGbc Tt0Ykn5PL+pL999F+l29mWeLrGgGunvZZNVFjj80NZBgvii6ugk7/949NM9t /ytqejqTpv+5xoZ2jORfiyr9aTPQ/e822XVehL09viyqzHY2K8pyer3550t8 mLqo6ga27cqRDjz60/3H09dPH0/er7Pu8gRf9v+6rLnIu5P0suvW7cnh4fX1 9fT6/tSN5PD89eHRo0ePDvXdCXw8OnLEH7XBB/T3L56nr9xz6XM33Y2jw/Tu 7+HzQfpv7mi6OaVH03uj6GWlhejfJKXl+Rf3/+4kl1nzbuczb7r8Kk+f5K/r No8ewhOUntVXOZyoFGYQPdHmTZG3RbWs+4MYubUbnTj2QoS8wJ1JBxYkgfeD VX92enY6efHyyeTs9MXTN71l5yVDZuMO5abM0zOY6W2Xx23QCfYxON9lVvZW YminC8cucK8zx4EuKjyrh1u3e5N11rjhdG7fDv103AbvmgiwrRQI4HV+Ubjj v/0HmMj7VTlpeDg0i9ffP568Of/D86e7pvGm27qdwBvhoybgGk6feu7wqdNw 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 WTNGAgA=[rfced] We have the following questions related to the use of <tt> element to mark certain terms in the XML file. a) Please review instances in which more than one term is enclosed in the <tt> tag. For example, should: <tt>"<b>" and "</b>"</tt> be made <tt>"<b>"</tt> and <tt>"</b>"</tt> and we see both: <tt>"<CODE BEGINS>" and "<CODE ENDS>"</tt> and <tt>"<CODE BEGINS>"</tt> and <tt>"<CODE ENDS>"</tt> b) Please review the use of quotation marks (both single quotes and double quotes) with these terms; specifically, should they be moved to outside the <tt> tag? For example, we see both: <tt>"<CODE BEGINS>"</tt> tag and <tt><CODE BEGINS></tt> convention c) Please review to ensure the usage of <tt> is consistent. It appears that there may be varying treatment of these terms. d) Please review the use of <tt><> with URLs. Should these instead use <eref>? For example: Original: <tt><https://www.ietf.org/id-info/guidelines.html></tt> Perhaps: <eref target="https://www.ietf.org/id-info/guidelines.html" brackets="angle"/> e) Other than CODE BEGINS / ENDS and URLs, we see the following uses of <tt>. Please confirm these appear as you intended. <tt>'//chapter[42]'</tt> <tt>"<b>" and "</b>"</tt> <tt><get></tt> <tt>'*'</tt> --> <!-- [rfced] Please review the "Inclusive Language" portion of the online Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language> and let us know if any changes are needed. Updates of this nature typically result in more precise language, which is helpful for readers. Note that our script did not flag any words in particular, but this should still be reviewed as a best practice. --> </back> </rfc>