RFC 9907: BCP 216: Guidelines for Authors and Reviewers of Documents Containing YANG Data Models

1.1. Changes Since RFC 8407

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

2.1. NETCONF Terms

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

2.2. YANG Terms

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

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

2.3. Network Management Datastore Architecture (NMDA) Terms

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

2.4. Requirements Notation

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

2.5. YANG Data Model versus YANG Module

Both [RFC6020] and [RFC7950] make a distinction between the following concepts:¶

data model:

Describes how data is represented and accessed.¶

YANG structures data models into modules for ease of use [RFC8309].¶

module:

Defines hierarchies of schema nodes to make a self-contained and compilable block of YANG definitions and inclusions.¶

A YANG module is typically a single ".yang" file, starting with a "module" statement.¶

A YANG module may include any number of submodules that are stored in separate ".yang" files starting with a "submodule" statement. Regardless of the presence of submodules, the module and its submodules are externally viewed as a single YANG module.¶

A YANG data model can consist of:¶

Note that the term "YANG model" is sometimes used as an abbreviation of "YANG data model". However, that term should be avoided in favor of "YANG data model". Likewise, "YANG data module" has no meaning and must be avoided.¶

Even if a YANG data model is structured as a single YANG module, the term "YANG data model" should be used in the title, abstract, and in the body of the document where the overall design is described. "YANG module" should be used when a specific "*.yang" file is referenced. Likewise, "YANG module" should be used when using terms related to YANG module specifications (e.g., augmentation or deviation). However, when extending the concepts embodied in a YANG module, authors should refer to those as an extension to the "YANG data model".¶

3.1. Module Copyright

The module "description" statement MUST contain a reference to the latest approved IETF Trust Copyright statement, which is available at: <https://trustee.ietf.org/license-info/>.¶

3.2. Code Components

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

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

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

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

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

<CODE ENDS>

3.3. Terminology Section

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

3.4. Tree Diagrams

YANG tree diagrams provide a concise representation of a YANG module and SHOULD be included to help readers understand YANG module structure. Guidelines on tree diagrams can be found in Section 3 of [RFC8340]. Tree diagrams longer than one page SHOULD be included in an appendix, i.e., not in the main body of the document.¶

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

3.5. Narrative Sections

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. The narrative part SHOULD include one or more sections to briefly describe the structure of the data models defined in the specification.¶

If the module (or modules) defined by the specification imports definitions from other modules (except for those defined in [RFC7950] or [RFC9911]) 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. Refer to Section 2.3 of [RFC8349] for an example of this overview section.¶

If the document contains major Network Management Datastore Architecture (NMDA) exceptions or includes a temporary non-NMDA module [RFC8342], then the Introduction section SHOULD mention this fact with the reasoning that motivated that design. Refer to Section 4.23 for more NMDA-related guidance. Specifically, Section 4.23.2 includes a recommendation for designers to describe and justify any NMDA exceptions in detail as part of the module itself.¶

Consistent indentation SHOULD be used for all examples, including YANG fragments and protocol message instance data. If line wrapping is used for formatting purposes, then this SHOULD be indicated per the guidance in [RFC8792], as shown in the following example:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

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

Built-in YANG features (e.g., breaking line, "+") SHOULD be used to fit a module into the line limits. Exceptionally, YANG modules MAY be folded as described in RFC 8792 if and only if built-in YANG features are not sufficient. A similar approach (e.g., using "--tree-line-length 69" or splitting a tree into subtrees) SHOULD be followed for tree diagrams.¶

3.6. Definitions Section

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

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

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

Example YANG modules and example YANG fragments MUST NOT contain any normative text, including any key words from [RFC2119] and [RFC8174].¶

Consistent indentation and formatting (e.g., folding) SHOULD be used in all YANG statements within a module.¶

See Section 4 for guidelines on YANG usage.¶

3.7. Security Considerations Section

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

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>). Section 3.7.1 contains the security considerations template. Authors MUST check the web page at the URL listed above in case there is a more recent version available.¶

In particular:¶

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].¶

<BEGIN TEMPLATE TEXT>

X.  Security Considerations

This section is modeled after the template described in Section 3.7.1
of [RFC9907].

The "<module-name>" YANG module defines a data model that is
designed to be accessed via YANG-based management protocols,
such as the Network Configuration Protocol (NETCONF) [RFC6241]
and RESTCONF [RFC8040].  These YANG-based management protocols
(1) have to use a secure transport layer (e.g., Secure Shell (SSH)
[RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use
mutual authentication.

The Network Configuration Access Control Model (NACM) [RFC8341]
provides the means to restrict access for particular NETCONF or
RESTCONF users to a preconfigured subset of all available NETCONF or
RESTCONF protocol operations and content.

-- Note: RFC 8341 (or a future RFC that replaces it) MUST be listed
-- as a normative reference.

-- By default, RFC 4252, RFC 6241, RFC 8040, RFC 8446, RFC 9000, and
-- RFC 9907 (or future RFCs that replace any of them) are listed as
-- informative references unless normatively cited in other sections
-- of the document that specifies the YANG module.

-- Writable nodes section:
--
-- If the data model contains any writable data nodes (those are all
-- the "config true" nodes), then include the following text:

There are a number of data nodes defined in this YANG module that are
writable/creatable/deletable (i.e., "config true", which is the
default).  All writable data nodes are likely to be sensitive or
vulnerable in some network environments.  Write
operations (e.g., edit-config) and delete operations to these data
nodes without proper protection or authentication can have a negative
effect on network operations.  The following subtrees and data nodes
have particular sensitivities/vulnerabilities:

-- If the data model contains any particularly sensitive data nodes,
-- e.g., ones that are protected by a "nacm:default-deny-write"
-- or a "nacm:default-deny-all" extensions statement, then those
-- subtrees and data nodes must be listed, with an explanation of the
-- associated security risks with a focus on how they can be
-- disruptive if abused.  Otherwise, state:
--
-- "There are no particularly sensitive writable data nodes."

-- Readable nodes section:
--
-- If the data model contains any readable data nodes (i.e., those
-- that are "config false" nodes, but also all other nodes because
-- they can also be read via operations like get or get-config), then
-- include the following text:

Some of the readable data nodes in this YANG module may be considered
sensitive or vulnerable in some network environments.  It is thus
important to control read access (e.g., via get, get-config, or
notification) to these data nodes.  Specifically, the following
subtrees and data nodes have particular sensitivities/
vulnerabilities:

-- You must evaluate whether the data model contains any readable
-- data nodes (those are all the "config false" nodes, but also all
-- other nodes because they can also be read via operations like get
-- or get-config) that are particularly sensitive or vulnerable
-- (e.g., if they might reveal customer information or violate
-- personal privacy laws).  Typically, particularly sensitive
-- readable data nodes are ones that are protected by a
-- "nacm:default-deny-read" or a "nacm:default-deny-all" extensions
-- statement.
--
-- Otherwise, state:
-- "There are no particularly sensitive readable data nodes."

-- RPC/action operations section:
--
-- If the data model contains any RPC or action operations, then
-- include the following text:

Some of the RPC or action operations in this YANG module may be
considered sensitive or vulnerable in some network environments.
It is thus important to control access to these operations.
Specifically, the following operations have particular
sensitivities/ vulnerabilities:

-- If the data model contains any particularly sensitive RPC
-- or action operations, then those operations must be listed
-- here, along with an explanation of the associated specific
-- sensitivity or vulnerability concerns.
--
-- Otherwise, state:
-- "There are no particularly sensitive RPC or action operations."

-- Reusable groupings from other modules section:
--
-- If the data model reuses groupings from other modules and
-- the document that specifies these groupings also
-- includes those as data nodes, then add this text as a
-- reminder of the specific sensitivity or vulnerability of
-- reused nodes.

This YANG module uses groupings from other YANG modules that
define nodes that may be considered sensitive or vulnerable
in network environments.  Refer to the Security Considerations
of <RFC-insert-numbers> for information as to which nodes may
be considered sensitive or vulnerable in network environments.

-- No data nodes section:
--
-- If the data model does not define any data nodes (i.e., none
-- of the above sections or readable/writable data nodes or RPCs
-- have been included), then add the following text:

The YANG module defines a set of identities, types, and
groupings.  These nodes are intended to be reused by other YANG
modules.  The module by itself does not expose any data nodes that
are writable, data nodes that contain read-only state, or RPCs.
As such, there are no additional security issues related to
the YANG module that need to be considered.

Modules that use the groupings that are defined in this document
should identify the corresponding security considerations.  For
example, reusing some of these groupings will expose privacy-related
information (e.g., 'node-example').

<END TEMPLATE TEXT>

3.8. IANA Considerations Section

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

Additional IANA considerations applicable to IANA-maintained YANG modules (including instructions to maintain them) are provided in Section 4.30.3.¶

IANA is requested to register the following URI in the "ns"
registry within the "IETF XML Registry" group [RFC3688]:

   URI:
   Registrant Contact:  The IESG
   XML: N/A; the requested URI is an XML namespace.

IANA is requested to register the following YANG module in the "YANG
Module Names" registry [RFC6020] within the "YANG Parameters"
registry group.

   Name:
   Maintained by IANA?  Y/N
   Namespace:
   Prefix:
   Reference:

IANA is requested to update the following registration in the "ns"
registry within the "IETF XML Registry" group [RFC3688] to
reference this document:

   URI:
   Registrant Contact:  The IESG
   XML: N/A; the requested URI is an XML namespace.

IANA is requested to register the following YANG module in the "YANG
Module Names" registry [RFC6020] [RFC9890] within the "YANG Parameters"
registry group.

   Name:
   Maintained by IANA?  Y/N
   Namespace:
   Prefix:
   Reference:

3.9. References Sections

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

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

3.10. Validation Tools

All modules need to be validated before submission in an I-D. The 'pyang' YANG compiler is freely available from GitHub: <https://github.com/mbj4668/pyang>.¶

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

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

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.¶

The 'yanglint' program is also freely available from GitHub: <https://github.com/CESNET/libyang>.¶

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

To check that JSON-encoded examples [RFC7951] comply with the target data models, programs such as 'yangson' or 'yanglint' should be used. Both programs are freely available from GitHub: <https://github.com/CZ-NIC/yangson> and <https://github.com/CESNET/libyang>.¶

3.11. Module Extraction Tools

A version of 'rfcstrip' that will extract YANG modules from an I-D or RFC is freely available at: <https://github.com/mbj4668/rfcstrip>.¶

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

The 'xym' tool is freely available on GitHub and can be used to extract YANG modules from a document: <https://github.com/xym-tool/xym>.¶

3.12. Module Usage Examples

Each specification that defines one or more modules SHOULD contain usage examples, either throughout the document or in an appendix. This includes example instance document snippets in an appropriate encoding (e.g., XML and/or JSON) to demonstrate the intended usage of the YANG module(s). Examples that are meant to illustrate a valid data instance MUST be validated (Section 3.10). Refer to Section 3.10 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 SHOULD be used in the examples.¶

For some types (IP addresses, domain names, etc.), the IETF has reserved values for documentation use. Authors SHOULD use these reserved values in the usage examples if these types are used. Examples of reserved values are listed below:¶

URI examples SHOULD be prefixed with "example:".¶

In order to ease extraction and validation of examples, it is RECOMMENDED to use code markers.¶

4.1. Module Naming Conventions

Normative modules contained in Standards Track documents MUST be named according to the guidelines in the IANA Considerations section of [RFC6020].¶

A distinctive word or abbreviation (e.g., protocol name or working group abbreviation) SHOULD be used in the module name. If new definitions are being defined to extend one or more existing modules, then the same word or abbreviation should be reused, instead of creating a new one.¶

All published module names MUST be unique. For a YANG module published in an RFC, this uniqueness is guaranteed by IANA (Section 14 of [RFC6020]). For unpublished modules, the authors need to check that no other work in progress is using the same module name.¶

Example modules are non-normative and SHOULD be named with the prefix "example-".¶

It is suggested that a stable module name prefix be selected that represents the entire organization. All normative YANG modules published by the IETF MUST begin with the prefix "ietf-". All IANA-maintained YANG modules MUST begin with the prefix "iana-". Another standards organization, such as the IEEE, might use the prefix "ieee-" for all YANG modules.¶

Once a module name is published, it MUST NOT be reused, even if the RFC containing the module is reclassified to "Historic" status. A module name cannot be changed in YANG, and this would be treated as a new module, not a name change.¶

4.2. Prefixes

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:¶

    module example-foo {
      namespace "tag:example.com,2017:example-foo";
      prefix f;

      container foo;
    }

    module example-bar {
      namespace "tag:example.com,2017:example-bar";
      prefix b;

      typedef foo { type uint32; }
    }

    module example-one {
      namespace "tag:example.com,2017:example-one";
      prefix one;
      import example-foo { prefix f; }
      import example-bar { prefix b; }

      augment "/f:foo" {
        leaf foo { type b:foo; }
      }
    }

YANG defines the following rules for prefix usage:¶

The following guidelines apply to prefix usage of the current (local) module:¶

Consistent with Section 7.1.4 of [RFC7950], the prefix defined by a module SHOULD be used when the module is imported, unless there is a conflict.¶

Prefix values SHOULD be short but meaningful to the intended user. Prefix values SHOULD NOT conflict with known modules that have been previously published.¶

For convenience, prefix values of example modules SHOULD 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.¶

4.3. Identifiers

All YANG identifiers in published modules MUST be between 1 and 64 characters in length. These include any construct specified as an "identifier-arg-str" token in the ABNF in Section 14 of [RFC7950].¶

4.4. Defaults

In general, it is suggested that substatements containing very common default values SHOULD NOT be present. The substatements listed in Table 1 are commonly used with the default value, which would make the module difficult to read if used everywhere they are allowed.¶

4.5. Conditional Statements

A module may be conceptually partitioned in several ways using the "if-feature" and/or "when" statements.¶

Data model designers need to carefully consider all modularity aspects, including the use of YANG conditional statements.¶

If a data definition is optional, depending on server support for a NETCONF or RESTCONF protocol capability, then a YANG "feature" statement SHOULD be defined. The defined "feature" statement SHOULD then be used in the conditional "if-feature" statement referencing the optional data definition.¶

If any notification data, or any data definition, for a non- configuration data node is not mandatory, then the server may or may not be required to return an instance of this data node. If any conditional requirements exist for returning the data node in a notification payload or retrieval request, they MUST be documented somewhere. For example, a "when" or "if-feature" statement could apply to the data node or the conditional requirements could be explained in a "description" statement within the data node or one of its ancestors (if any).¶

If any "if-feature" statements apply to a list node, then the same "if-feature" statements MUST apply to any key leaf nodes for the list. There MUST NOT be any "if-feature" statements applied to any key leafs that do not also apply to the parent list node.¶

There SHOULD NOT be any "when" statements applied to a key leaf node. It is possible that a "when" statement for an ancestor node of a key leaf will have the exact node-set result as the key leaf. In such a case, the "when" statement for the key leaf is redundant and SHOULD be avoided.¶

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 SHOULD NOT be used.¶

    leaf type {
      type enumeration {
        enum a;
        enum b;
        enum c;
      }
      mandatory true;
    }
    choice type-choice {
      case b {
        container type-b {
          when "../type = 'b'";
          leaf foo {
            type string;
          }
        }
      }
      case c {
        container type-c {
          when "../type = 'c'";
          leaf bar {
            mandatory true;
            type string;
          }
        }
      }
    }

The following example removes the duplicated information:¶

    leaf type {
      type enumeration {
        enum a;
        enum b;
        enum c;
      }
      mandatory true;
    }
    container type-b {
      when "../type = 'b'";
      leaf foo {
        type string;
      }
    }
    container type-c {
      when "../type = 'c'";
      leaf bar {
        mandatory true;
        type string;
      }
    }

Note that the use of "case + when" is still useful in cases where complementary modeling constraints should be expressed. See the example provided below:¶

    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;
          }
        }
      }
    }

Section 8.1 of [RFC7950] includes provisions for defining constraints on state data and specifies that a constraint must be true in a valid state data tree. However, Section 5.3 of [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 behavior versus intended behavior of a managed entity and hopefully trigger corrective actions by a management system. From that perspective, it is RECOMMENDED to avoid defining constraints on state data that would hinder the detection by a management system of abnormal behaviors of a managed entity.¶

4.6. XPath Usage

This section describes guidelines for using the XML Path Language (XPath) [W3C.REC-xpath] within YANG modules.¶

    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";
        }
      }
    }

   /*[local-name()='foo']

 // 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')";

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
}

   when /foo/services/*/active {
     description
       "No services directly defined in this module.
        Matches objects that have augmented the services container.";
   }

     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;
     }

     leaf foo1 {
       type enumeration {
         enum one;
         enum two;
         enum three;
         enum four;
       }
     }

4.7. YANG Definition Lifecycle Management

The YANG status statement MUST be present within a definition if its value is "deprecated" or "obsolete". The status SHOULD NOT be changed from "current" directly to "obsolete". An object SHOULD be available for at least one year after the publication date with a "deprecated" status before it is changed to "obsolete".¶

The module or submodule name MUST NOT be changed once the document containing the module or submodule is published.¶

The module namespace URI value MUST NOT be changed once the document containing the module is published.¶

The revision date substatement within the "import" statement SHOULD be present if any groupings are used from the external module.¶

The revision date substatement within the "include" statement SHOULD be present if any groupings are used from the external submodule.¶

If an "import" statement is for a module from a stable source (e.g., an RFC for an IETF module), then a reference-stmt SHOULD be present within an "import" statement.¶

     import ietf-yang-types {
        prefix yang;
        reference "RFC 9911: Common YANG Data Types";
     }

If submodules are used, then the document containing the main module MUST be updated so that the main module revision date is equal to or more recent than the revision date of any submodule that is (directly or indirectly) included by the main module.¶

Definitions for future use SHOULD NOT be specified in a module. Do not specify placeholder objects like the "reserved" example below:¶

    leaf reserved {
      type string;
      description
        "This object has no purpose at this time, but a future
         revision of this module might define a purpose
         for this object.";
    }

4.8. Module Header, Meta, and Revision Statements

For published modules, the namespace MUST be a globally unique URI, as defined in [RFC3986]. This value is usually assigned by the IANA.¶

The "organization" statement MUST be present. If the module is contained in a document intended for IETF Standards Track status, then the organization SHOULD be the IETF working group (WG) chartered to write the document. Exceptions include (but are not limited to): example modules, IANA-maintained YANG modules, or modules contained in AD-sponsored documents. For other standards organizations, a similar approach is also suggested.¶

The "contact" statement MUST be present. If the module is contained in a document intended for Standards Track status, then the WG web and mailing information SHOULD be present, and the main document author or editor contact information SHOULD be present. If additional authors or editors exist, their contact information MAY be present. There is no need to include the contact information for WG Chairs.¶

The "description" statement MUST be present. For modules published within IETF documents, the appropriate IETF Trust Copyright text MUST be present, as described in Section 3.1, and MUST contain the following statement:¶

All revisions of IETF and IANA published modules can be found at the "YANG Parameters" registry group: <https://www.iana.org/assignments/yang-parameters>.¶

If the module relies on information contained in other documents, which are not the same documents implied by the "import" statements present in the module, then these documents MUST be identified in the "reference" statement.¶

A "revision" statement MUST be present for each published version of the module. The "revision" statement MUST have a "reference" substatement. It MUST identify the published document that contains the module. Modules are often extracted from their original documents, and it is useful for developers and operators to know how to find the original source document in a consistent manner. The "revision" statement MAY have a "description" substatement. 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 [ID-Guidelines].¶

The following example shows the "revision" statement for a published YANG module:¶

   revision 2010-09-24 {
     description
       "Initial revision.";
   reference
     "RFC 6021: Common YANG Data Types";
   }

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.¶

  revision 2013-07-15 {
    description
      "This revision adds the following new data types:
       - yang:yang-identifier
       - yang:hex-string
       - yang:uuid
       - yang:dotted-quad";
     reference
       "RFC 6991: Common YANG Data Types";
   }

   revision 2010-09-24 {
     description
       "Initial revision.";
   reference
     "RFC 6021: Common YANG Data Types";
   }

For an unpublished module, a complete history of each unpublished module revision is not required. That is, within a sequence of draft versions, only the most recent revision need be recorded in the module. Do not remove or reuse a "revision" statement for a published module. A new revision date is not required unless the module contents have changed. If the module contents have changed, then the revision date of that new module version MUST be updated to a date later than that of the previous version.¶

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.¶

  revision 2025-12-22 {
    description
      "This revision adds the following new data types:
       - yang:date
       - yang:date-no-zone
       - yang:time
       - yang:time-no-zone
       - yang:hours32
       - yang:minutes32
       - yang:seconds32
       - yang:centiseconds32
       - yang:milliseconds32
       - yang:microseconds32
       - yang:microseconds64
       - yang:nanoseconds32
       - yang:nanoseconds64
       - yang:language-tag
       The yang-identifier definition has been aligned with YANG
       1.1 and types representing time support the representation
       of leap seconds.  The representation of time zone offsets
       has been aligned with RFC 9557.  Several description and
       pattern statements have been improved.";
    reference
      "RFC 9911: Common YANG Data Types";
   }

  revision 2013-07-15 {
    description
      "This revision adds the following new data types:
       - yang:yang-identifier
       - yang:hex-string
       - yang:uuid
       - yang:dotted-quad";
     reference
       "RFC 6991: Common YANG Data Types";
   }

   revision 2010-09-24 {
     description
       "Initial revision.";
   reference
     "RFC 6021: Common YANG Data Types";
   }

4.9. Namespace Assignments

It is RECOMMENDED that only valid YANG modules be included in documents, whether or not the modules are published yet. This allows:¶

Until a URI is assigned by the IANA, a proposed namespace URI MUST be provided for the "namespace" statement in a YANG module. A value SHOULD be selected that is not likely to collide with other YANG namespaces. Standard module names, prefixes, and URI strings already listed in the "YANG Module Names" registry group MUST NOT be used.¶

A standard "namespace" statement value SHOULD have the following form:¶

    <URN prefix string>:<module-name>

The following URN prefix string SHOULD be used for published and unpublished YANG modules:¶

    urn:ietf:params:xml:ns:yang

The following example URNs would be valid "namespace" statement values for Standards Track modules:¶

    urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock

    urn:ietf:params:xml:ns:yang:ietf-netconf-state

    urn:ietf:params:xml:ns:yang:ietf-netconf

Note that a different URN prefix string SHOULD be used for modules that are not Standards Track. The string SHOULD be selected according to the guidelines in Section 5.3 of [RFC7950].¶

The following URIs exemplify what might be used by modules that are not Standards Track. Note that the domain "example.com" SHOULD be used by example modules in I-Ds from the IETF Stream. These URIs are not intended to be dereferenced. They are used for module namespace identification only.¶

Example URIs using URLs per [RFC3986]:¶

    https://example.com/ns/example-interfaces

    https://example.com/ns/example-system

Example URIs using tags per [RFC4151]:¶

    tag:example.com,2017:example-interfaces

    tag:example.com,2017:example-system

4.10. Top-Level Data Definitions

The top-level data organization SHOULD be considered carefully, in advance. Data model designers need to consider how the functionality for a given protocol or protocol family will grow over time.¶

The separation of configuration data and operational state SHOULD be considered carefully. It is sometimes useful to define separate top- level containers for configuration and non-configuration data. For some existing top-level data nodes, configuration data was not in scope, so only one container representing operational state was created. Refer to NMDA [RFC8342] for details.¶

The number of top-level data nodes within a module SHOULD be minimized. It is often useful to retrieve related information within a single subtree. If data is too distributed, it becomes difficult to retrieve all at once.¶

The names and data organization SHOULD reflect persistent information, such as the name of a protocol. The name of the working group SHOULD NOT be used because this may change over time.¶

A mandatory database data definition is defined as a node that a client must provide for the database to be valid. The server is not required to provide a value.¶

Top-level database data definitions MUST NOT be mandatory. If a mandatory node appears at the top level, it will immediately cause the database to be invalid. This can occur when the server boots or when a module is loaded dynamically at runtime.¶

4.11. Data Types

Selection of an appropriate data type (i.e., built-in type, existing derived type, or new derived type) is very subjective; therefore, few requirements can be specified on that subject.¶

Data model designers SHOULD use the most appropriate built-in data type for the particular application.¶

The signed numeric data types (i.e., "int8", "int16", "int32", and "int64") SHOULD NOT be used unless negative values are allowed for the desired semantics.¶

    leaf foo {
      type enumeration {
        enum one;
        enum two;
      }
    }

    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;
      }
    }

    typedef ipv6-address-no-zone {
      type inet:ipv6-address {
        pattern '[0-9a-fA-F:\.]*';
      }
      ...
    }

    typedef yang-identifier {
      type string {
        length "1..max";
        pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
        pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
      }
      ...
    }

    typedef dscp {
      type uint8 {
        range "0..63";
      }
      ...
    }

    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...  ";
    }

   type union {
     type string;
     type enumeration {
       enum up;
       enum down;
     }
   }

   type union {
     type enumeration {
       enum up;
       enum down;
     }
     type string;
   }

   type union {
     type string;
     type int32;
   }

   type union {
     type int32;
     type string;
   }

   leaf flag1 {
     type empty;
   }

   leaf flag2 {
     type boolean;
     default false;
   }

4.12. Reusable Type Definitions

If an appropriate derived type exists in any standard module, such as [RFC9911], then it SHOULD be used instead of defining a new derived type.¶

If an appropriate units identifier can be associated with the desired semantics, then a units statement SHOULD be present.¶

If an appropriate default value can be associated with the desired semantics, then a default statement SHOULD be present.¶

If a significant number of derived types are defined, and it is anticipated that these data types will be reused by multiple modules, then these derived types SHOULD be contained in a separate module or submodule to allow easier reuse without unnecessary coupling.¶

The "description" statement MUST be present.¶

If the type definition semantics are defined in an external document (other than another YANG module indicated by an "import" statement), then the "reference" statement MUST be present.¶

4.13. Reusable Groupings

A reusable grouping is a YANG grouping that can be imported by another module and is intended for use by other modules. This is not the same as a grouping that is used within the module in which it is defined, but it happens to be exportable to another module because it is defined at the top level of the YANG module.¶

The following guidelines apply to reusable groupings, in order to make them as robust as possible:¶

4.14. Data Definitions

The "description" statement MUST be present in the following YANG statements:¶

If the data definition semantics are defined in an external document, (other than another YANG module indicated by an "import" statement), then a "reference" statement MUST be present.¶

The "anyxml" construct may be useful to represent an HTML banner containing markup elements, such as "<b>" and "</b>", and MAY be used in such cases. However, this construct SHOULD NOT be used if other YANG data node types can be used instead to represent the desired syntax and semantics.¶

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.¶

If there are referential integrity constraints associated with the desired semantics that can be represented with XPath, then one or more "must" statements SHOULD be present.¶

For list and leaf-list data definitions, if the number of possible instances is required to be bounded for all implementations, then the max-elements statements SHOULD be present.¶

If any "must" or "when" statements are used within the data definition, then the data definition "description" statement SHOULD describe the purpose of each one.¶

The "choice" statement is allowed to be directly present within a "case" statement in YANG 1.1. This needs to be considered carefully. Consider simply including the nested "choice" as additional "case" statements within the parent "choice" statement. Note that the "mandatory" and "default" statements within a nested "choice" statement only apply if the "case" containing the nested "choice" statement is first selected.¶

If a list defines any key leafs, then these leafs SHOULD be defined in order, as the first child nodes within the list. The key leafs MAY be in a different order in some cases, e.g., they are defined in a grouping, and not inline in the list statement.¶

    container top {
       container foos {
          list foo { ... }
       }
       container bars {
          list bar { ... }
       }
    }

    container top {
       list foo { ... }
       list bar { ... }
    }

4.15. Operation Definitions

If the operation semantics are defined in an external document (other than another YANG module indicated by an "import" statement), then a "reference" statement MUST be present.¶

If the operation impacts system behavior in some way, it SHOULD be mentioned in the "description" statement.¶

If the operation is potentially harmful to system behavior in some way, it MUST be mentioned in the Security Considerations section of the document.¶

4.16. Notification Definitions

The "description" statement MUST be present.¶

If the notification semantics are defined in an external document (other than another YANG module indicated by an "import" statement), then a "reference" statement MUST be present.¶

If the notification refers to a specific resource instance, then this instance SHOULD be identified in the notification data. This is usually done by including "leafref" leaf nodes with the key leaf values for the resource instance. For example:¶

  notification interface-up {
    description "Sent when an interface is activated.";
    leaf name {
      type leafref {
        path "/if:interfaces/if:interface/if:name";
      }
    }
  }

Note that there are no formal YANG statements to identify any data node resources associated with a notification. The "description" statement for the notification SHOULD specify if and how the notification identifies any data node resources associated with the specific event.¶

4.17. Feature Definitions

The YANG "feature" statement is used to define a label for a set of optional functionality within a module. The "if-feature" statement is used in the YANG statements associated with a feature. The description-stmt within a feature-stmt MUST specify any interactions with other features.¶

The set of YANG features defined in a module should be considered carefully. Very fine granular features increase interoperability complexity and should be avoided. A likely misuse of the feature mechanism is the tagging of individual leafs (e.g., counters) with separate features.¶

If there is a large set of objects associated with a YANG feature, then consider moving those objects to a separate module instead of using a YANG feature. Note that the set of features within a module is easily discovered by the reader, but the set of related modules within the entire YANG library is not as easy to identify. Module names with a common prefix can help readers identify the set of related modules, but this assumes the reader will have discovered and installed all the relevant modules.¶

Another consideration for deciding whether to create a new module or add a YANG feature is the stability of the module in question. It may be desirable to have a stable base module that is not changed frequently. If new functionality is placed in a separate module, then the base module does not need to be republished. If it is designed as a YANG feature, then the module will need to be republished.¶

If one feature requires implementation of another feature, then an "if-feature" statement SHOULD be used in the dependent "feature" statement.¶

For example, feature2 requires implementation of feature1:¶

   feature feature1 {
     description "Some protocol feature";
   }

   feature feature2 {
     if-feature "feature1";
     description "Another protocol feature";
   }

4.18. YANG Data Node Constraints

4.19. "augment" Statements

The YANG "augment" statement is used to define a set of data definition statements that will be added as child nodes of a target data node. The module namespace for these data nodes will be the augmenting module, not the augmented module.¶

A top-level "augment" statement SHOULD NOT be used if the target data node is in the same module or submodule as the evaluated "augment" statement. The data definition statements SHOULD be added inline instead.¶

     augment "/if:interfaces/if:interface" {
         when "if:type = 'ianaift:ethernetCsmacd'";

         container ethernet {
             leaf duplex {
                 ...
             }
         }
     }

  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;
      }
    }
  }

4.20. Deviation Statements

Per Section 7.20.3 of [RFC7950], the YANG "deviation" statement is not allowed to appear in IETF YANG modules, but it can be useful for documenting server capabilities. Deviation statements are not reusable and typically not shared across all platforms.¶

There are several reasons that deviations might be needed in an implementation, e.g., an object cannot be supported on all platforms, or feature delivery is done in multiple development phases. Deviation statements can also be used to add annotations to a module, which does not affect the conformance requirements for the module.¶

It is suggested that deviation statements be defined in separate modules from regular YANG definitions. This allows the deviations to be platform specific and/or temporary.¶

The order that deviation statements are evaluated can affect the result. Therefore, multiple deviation statements in the same module, for the same target object, SHOULD NOT be used.¶

The "max-elements" statement is intended to describe an architectural limit to the number of list entries. It is not intended to describe platform limitations. It is better to use a "deviation" statement for the platforms that have a hard resource limit.¶

Example documenting platform resource limits:¶

Wrong: (max-elements in the list itself)¶

     container backups {
       list backup {
         ...
         max-elements 10;
         ...
       }
     }

Correct: (max-elements in a deviation)¶

     deviation /bk:backups/bk:backup {
       deviate add {
         max-elements 10;
       }
     }

4.21. Extension Statements

The YANG "extension" statement is used to specify external definitions. This appears in the YANG syntax as an "unknown-statement". Usage of "extension" statements in a published module needs to be considered carefully.¶

The following guidelines apply to the usage of YANG extensions:¶

4.22. Data Correlation

Data can be correlated in various ways, using common data types, common data naming, and common data organization. There are several ways to extend the functionality of a module, based on the degree of coupling between the old and new functionality:¶

inline:

update the module with new protocol-accessible objects. The naming and data organization of the original objects is used. The new objects are in the original module namespace.¶

augment:

create a new module with new protocol-accessible objects that augment the original data structure. The naming and data organization of the original objects is used. The new objects are in the new module namespace.¶

mirror:

create new objects in a new module or the original module, except use a new naming scheme and data location. The naming can be coupled in different ways. Tight coupling is achieved with a "leafref" data type, with the "require-instance" substatement set to "true". This method SHOULD be used.¶

If the new data instances are not limited to the values in use in the original data structure, then the "require-instance" substatement MUST be set to "false". Loose coupling is achieved by using key leafs with the same data type as the original data structure. This has the same semantics as setting the "require-instance" substatement to "false".¶

The relationship between configuration and operational state has been clarified in NMDA [RFC8342].¶

   list foo {
      key name;
      leaf name {
         type string;
      }
      ...
   }

   list foo-addon {
      key name;
      config false;
      leaf name {
         type string;
      }
      ...
   }

   list foo {
      key name;
      leaf name {
         type string;
      }
      ...
   }

   list foo-addon {
      key name;
      config false;
      leaf name {
         type leafref {
            path "/foo/name";
            require-instance false;
         }
      }
      leaf addon {
         type string;
         mandatory true;
      }
   }

4.23. Operational State

The modeling of operational state with YANG has been refined over time. At first, only data that has a "config" statement value of "false" was considered to be operational state. This data was not considered to be part of any datastore, which made the YANG XPath definition much more complicated.¶

Operational state is now modeled using YANG according to the NMDA [RFC8342] and conceptually contained in the operational state datastore, which also includes the operational values of configuration data. There is no longer any need to duplicate data structures to provide separate configuration and operational state sections.¶

This section describes some data modeling issues related to operational state and guidelines for transitioning YANG data model design to be NMDA compatible.¶

   container foo {
     ...
     // contains "config true" and "config false" nodes that have
     // no corresponding "config true" object (e.g., counters)
   }

  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
    }
 }

  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
    }
 }

  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
    }
 }

  module example-foo-state {
    namespace "urn:example:params:xml:ns:yang:example-foo-state";
    prefix "foo-s";

    // import new or converted module; not used in this example
    import example-foo { prefix foo; }

    container foo-state {
      config false;
      status deprecated;
      // operational state child nodes
     }
  }

4.24. Performance Considerations

It is generally likely that certain YANG statements require more runtime resources than other statements. Although there are no performance requirements for YANG validation, the following information MAY be considered when designing YANG data models:¶

4.25. Open Systems Considerations

Only the modules imported by a particular module can be assumed to be present in an implementation. An open system MAY include any combination of YANG modules.¶

4.26. Guidelines for Constructs Specific to YANG 1.1

The set of guidelines for YANG 1.1 will grow as operational experience is gained with the new language features. This section contains an initial set of guidelines for YANG 1.1 language features.¶

   rpc reset {
     input {
       leaf interface {
         type if:interface-ref;
         mandatory true;
         description "The interface to reset.";
       }
     }
   }

   container interfaces {
     list interface {
       ...
       action reset { }
     }
   }

4.27. Updating YANG Modules (Published versus Unpublished)

YANG modules can change over time. Typically, new data model definitions are needed to support new features. YANG update rules defined in Section 11 of [RFC7950] MUST be followed for published modules. They MAY be followed for unpublished modules.¶

The YANG update rules only apply to published module revisions. Each organization will have their own way to identify published work that is considered to be stable and unpublished work that is considered to be unstable. For example, in the IETF, an RFC is used for published work, and an I-D is used for unpublished work.¶

4.28. Defining Standard Tags

[RFC8819] specifies a method for associating tags with YANG modules. Tags may be defined and associated at design time, at implementation time, or via user administrative control. Design-time tags are indicated using the module-tag "extension" statement.¶

A module MAY indicate, using module-tag "extension" statements, a set of tags that are to be automatically associated with it (i.e., not added through configuration).¶

module example-module {
  namespace "https://example.com/yang/example";
  prefix "ex";
  //...
  import module-tags { prefix tags; }

  tags:module-tag "ietf:some-new-tag";
  tags:module-tag "ietf:some-other-tag";
  // ...
}

Authors can use existing standard tags or use new tags defined in the model definition, as appropriate. For IETF modules, new tags MUST be assigned in the IANA "IETF YANG Module Tags" registry within the "YANG Module Tags" registry group [IANA-TAGS].¶

4.29. Modeling Abstract Data Structures

For contexts where YANG is used to model abstract data structures (e.g., protocol messages), the use of the "structure" extension statement [RFC8791] is RECOMMENDED compared to the "yang-data" extension statement [RFC8040]. Examples of modules that rely upon the "structure" extension statement from [RFC8791] can be found in [RFC9132] or [RFC9195].¶

Abstract data structures can be augmented using the "augment-structure" statement [RFC8791]. Examples of modules that augment abstract data structures can be found in [RFC9244] and [RFC9362].¶

4.30. IANA-Maintained YANG Modules

  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";
  }

revision 2021-04-23 {
  description
    "Registered tunnelType 19.";
  reference
    "RFC 4301: Security Architecture for the Internet Protocol";
}

revision 2019-11-16 {
  description
    "Initial revision.";
  reference
    "RFC 8675: A YANG Data Model for Tunnel Interface Types";
}

...

identity ipsectunnelmode {
  base ift:tunnel;
  description
    "IpSec tunnel mode encapsulation.";
  reference
    "RFC 4301: Security Architecture for the Internet Protocol";
}

revision 2021-04-23 {
  description
    "Registered tunnelType 19.";
  reference
    "https://www.iana.org/assignments/yang-parameters/"
  + "iana-tunnel-type@2021-04-23.yang
     RFC 4301: Security Architecture for the Internet Protocol";
}

revision 2019-11-16 {
  description
    "Initial revision.";
  reference
    "RFC 8675: A YANG Data Model for Tunnel Interface Types";
}
...
identity ipsectunnelmode {
  base ift:tunnel;
  description
    "IpSec tunnel mode encapsulation.";
  reference
    "RFC 4301: Security Architecture for the Internet Protocol";
}

<BEGIN TEMPLATE TEXT>

This document defines the initial version of the IANA-maintained
"iana-foo" YANG module.  The most recent version of the YANG module
is available from the "YANG Parameters" registry group
[IANA-YANG-PARAMETERS].

IANA is requested to add this note to the registry:

   New values must not be directly added to the "iana-foo" YANG
   module.  They must instead be added to the "foo" registry.

IANA is requested to add this note to [reference-to-the-iana-foo-
registry]:

   When this registry is modified, the YANG module "iana-foo"
   [IANA_FOO_URL] must be updated as defined in RFC IIII.

When a value is added to the "foo" registry, a new "identity"
statement needs to be added to the "iana-foo" YANG module.
The name of the "identity" MUST be the name as provided in the
registry.  The "identity" statement should have the following
substatements defined:

 "base":        Contains 'name-base-identity-defined-in-foo'.

 "status":      Include only if a registration has been deprecated or
                obsoleted.  IANA "deprecated" maps to YANG status
                "deprecated", and IANA "obsolete" maps to YANG status
                "obsolete".

 "description":  Replicates the description from the registry.

 "reference":   Replicates the reference(s) from the registry with
                the title of the document(s) added.

-- Optional:

-- Include only text that needs to be customized for the module.
-- Text that does not require customization should be
-- omitted.

-- Notes tagged with "--" include instructions for authors.  These
-- notes must not be copied.

Unassigned and Reserved Values:

-- To be completed only if unassigned and/or reserved values
-- (which may include experimental values) should be included
-- in the module.  These values are typically not included.

Description Substatements:

-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements,
-- "identity" statements, or both.

Reference Substatements:

-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements,
-- "identity" statements, or both.

Naming Considerations:

-- If a name in the IANA registry does not comply with the
-- YANG naming conventions, add details how IANA can generate
-- legal identifiers.  For example, if the name begins with
-- a number, indicate a preference to spell out the number when
-- used as an identifier.

<END TEMPLATE TEXT>

<BEGIN TEMPLATE TEXT>

This document defines the initial version of the IANA-maintained
"iana-foo" YANG module.  The most recent version of the YANG module
is available from the "YANG Parameters" registry group
[IANA-YANG-PARAMETERS].

IANA is requested to add this note to the registry:

    New values must not be directly added to the "iana-foo" YANG
    module.  They must instead be added to the "foo" registry.

When a value is added to the "foo" registry, a new "enum" statement
must be added to the "iana-foo" YANG module.  The "enum" statement,
and substatements thereof, should be defined:

 "enum":        Replicates a name from the registry.

 "value":       Contains the decimal value of the IANA-assigned
                value.

 "status":      Is included only if a registration has been
                deprecated or obsoleted.  IANA "deprecated" maps
                to YANG status "deprecated", and IANA "obsolete"
                maps to YANG status "obsolete".

 "description":  Replicates the description from the registry.

 "reference":   Replicates the reference(s) from the registry.
                References to documents should also include titles.

-- Optional:

-- Include only text that needs to be customized for the module.
-- Text that does not require customization should be
-- omitted.

-- Notes tagged with "--" include instructions for authors.  These
-- notes must not be copied.

Unassigned and Reserved Values:

-- To be completed only if unassigned and/or reserved values
-- (which may include experimental values) should be included
-- in the module.  These values are typically not included.

Description Substatements:

-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements, "enum"
-- statements, or both.

Reference Substatements:

-- To be completed only if the default actions described in
-- Section 5.3.2 of RFC 9907 are to be overridden.
-- Specify whether instructions apply to "revision" statements, "enum"
-- statements, or both.

Naming Considerations:

-- If a name in the IANA registry does not comply with the
-- YANG naming conventions, add details how IANA can generate
-- legal identifiers.  For example, if the name begins with
-- a number, indicate a preference to spell out the number when
-- used as an identifier.

<END TEMPLATE TEXT>

5.1. YANG Modules

The following registration in the "ns" registry of the "IETF XML Registry" registry group [RFC3688] was detailed in [RFC8407]. IANA has updated this registration to reference this document.¶

URI:

urn:ietf:params:xml:ns:yang:ietf-template¶

Registrant Contact:

The IESG¶

XML:

N/A; the requested URI is an XML namespace.¶

IANA has registered the following URI in the "ns" registry within the "IETF XML Registry" registry group [RFC3688]:¶

URI:

urn:ietf:params:xml:ns:yang:iana-template¶

Registrant Contact:

The IESG¶

XML:

N/A; the requested URI is an XML namespace.¶

IANA has registered the following YANG modules in the "YANG Module Names" registry [RFC6020] [RFC9890] within the "YANG Parameters" registry group.¶

Name:

ietf-template¶

Maintained by IANA?

N¶

Namespace:

urn:ietf:params:xml:ns:yang:ietf-template¶

Prefix:

temp¶

Reference:

RFC 9907¶

Name:

iana-template¶

Maintained by IANA?

N¶

Namespace:

urn:ietf:params:xml:ns:yang:iana-template¶

Prefix:

iana-foo¶

Reference:

RFC 9907¶

5.2. Update in YANG Parameters Registry Group

For the references of the "YANG Module Names" registry under the "YANG Parameters" registry group, IANA has updated [RFC8407] to this document, as it contains the template necessary for registration in Appendix B.¶

5.3. IANA-Maintained YANG Modules

IANA should refer to Section 4.30.3 for information necessary to populate "revision" statements and "identity" and "enum" substatements in IANA-maintained YANG modules.¶

These considerations cover both the creation and maintenance of an IANA-maintained YANG module, and they include both instructions applicable to all IANA-maintained YANG modules and instructions that can be customized by module creators.¶

8.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC3688]

Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>.

[RFC5378]

Bradner, S., Ed. and J. Contreras, Ed., "Rights Contributors Provide to the IETF Trust", BCP 78, RFC 5378, DOI 10.17487/RFC5378, November 2008, <https://www.rfc-editor.org/info/rfc5378>.

[RFC6020]

Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.

[RFC6241]

Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.

[RFC7950]

Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>.

[RFC7952]

Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, August 2016, <https://www.rfc-editor.org/info/rfc7952>.

[RFC8040]

Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.

[RFC8126]

Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8341]

Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.

[RFC8342]

Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.

[RFC8791]

Bierman, A., Björklund, M., and K. Watsen, "YANG Data Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, June 2020, <https://www.rfc-editor.org/info/rfc8791>.

[RFC8792]

Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, "Handling Long Lines in Content of Internet-Drafts and RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, <https://www.rfc-editor.org/info/rfc8792>.

[RFC8819]

Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module Tags", RFC 8819, DOI 10.17487/RFC8819, January 2021, <https://www.rfc-editor.org/info/rfc8819>.

[RFC9890]

Bierman, A., Boucadair, M., Ed., and Q. Wu, "An Update to YANG Module Names Registration", RFC 9890, DOI 10.17487/RFC9890, October 2025, <https://www.rfc-editor.org/info/rfc9890>.

[W3C.REC-xpath]

Clark, J., Ed. and S. DeRose, Ed., "XML Path Language (XPath) Version 1.0", W3C Recommendation, 16 November 1999, <https://www.w3.org/TR/1999/REC-xpath-19991116>.

8.2. Informative References

[Err5693]

RFC Errata, Erratum ID 5693, RFC 8407, <https://www.rfc-editor.org/errata/eid5693>.

[Err5800]

RFC Errata, Erratum ID 5800, RFC 8407, <https://www.rfc-editor.org/errata/eid5800>.

[Err6899]

RFC Errata, Erratum ID 6899, RFC 8407, <https://www.rfc-editor.org/errata/eid6899>.

[Err7416]

RFC Errata, Erratum ID 7416, RFC 8407, <https://www.rfc-editor.org/errata/eid7416>.

[IANA-MOD-NAMES]

IANA, "YANG Module Names", <https://www.iana.org/assignments/yang-parameters/>.

[IANA-TAGS]

IANA, "YANG Module Tags", <https://www.iana.org/assignments/yang-module-tags/>.

[IANA-XML]

IANA, "IETF XML Registry", <https://www.iana.org/assignments/xml-registry/>.

[IANA-YANG-PARAMETERS]

IANA, "YANG Parameters", <https://www.iana.org/assignments/yang-parameters>.

[IANA_Tunnel_Type_URL]

IANA, "iana-tunnel-type YANG Module", <https://www.iana.org/assignments/iana-tunnel-type>.

[ID-Guidelines]

IETF, "Content guidelines overview", <https://authors.ietf.org/en/content-guidelines-overview>.

[RFC2026]

Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, <https://www.rfc-editor.org/info/rfc2026>.

[RFC2606]

Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS Names", BCP 32, RFC 2606, DOI 10.17487/RFC2606, June 1999, <https://www.rfc-editor.org/info/rfc2606>.

[RFC2863]

McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB", RFC 2863, DOI 10.17487/RFC2863, June 2000, <https://www.rfc-editor.org/info/rfc2863>.

[RFC3849]

Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix Reserved for Documentation", RFC 3849, DOI 10.17487/RFC3849, July 2004, <https://www.rfc-editor.org/info/rfc3849>.

[RFC4151]

Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 4151, DOI 10.17487/RFC4151, October 2005, <https://www.rfc-editor.org/info/rfc4151>.

[RFC4181]

Heard, C., Ed., "Guidelines for Authors and Reviewers of MIB Documents", BCP 111, RFC 4181, DOI 10.17487/RFC4181, September 2005, <https://www.rfc-editor.org/info/rfc4181>.

[RFC4252]

Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, January 2006, <https://www.rfc-editor.org/info/rfc4252>.

[RFC4253]

Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, January 2006, <https://www.rfc-editor.org/info/rfc4253>.

[RFC5398]

Huston, G., "Autonomous System (AS) Number Reservation for Documentation Use", RFC 5398, DOI 10.17487/RFC5398, December 2008, <https://www.rfc-editor.org/info/rfc5398>.

[RFC5612]

Eronen, P. and D. Harrington, "Enterprise Number for Documentation Use", RFC 5612, DOI 10.17487/RFC5612, August 2009, <https://www.rfc-editor.org/info/rfc5612>.

[RFC5737]

Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks Reserved for Documentation", RFC 5737, DOI 10.17487/RFC5737, January 2010, <https://www.rfc-editor.org/info/rfc5737>.

[RFC7223]

Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, <https://www.rfc-editor.org/info/rfc7223>.

[RFC7224]

Bjorklund, M., "IANA Interface Type YANG Module", RFC 7224, DOI 10.17487/RFC7224, May 2014, <https://www.rfc-editor.org/info/rfc7224>.

[RFC7407]

Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, December 2014, <https://www.rfc-editor.org/info/rfc7407>.

[RFC7951]

Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.

[RFC8199]

Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module Classification", RFC 8199, DOI 10.17487/RFC8199, July 2017, <https://www.rfc-editor.org/info/rfc8199>.

[RFC8299]

Wu, Q., Ed., Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data Model for L3VPN Service Delivery", RFC 8299, DOI 10.17487/RFC8299, January 2018, <https://www.rfc-editor.org/info/rfc8299>.

[RFC8309]

Wu, Q., Liu, W., and A. Farrel, "Service Models Explained", RFC 8309, DOI 10.17487/RFC8309, January 2018, <https://www.rfc-editor.org/info/rfc8309>.

[RFC8340]

Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.

[RFC8343]

Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.

[RFC8349]

Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for Routing Management (NMDA Version)", RFC 8349, DOI 10.17487/RFC8349, March 2018, <https://www.rfc-editor.org/info/rfc8349>.

[RFC8407]

Bierman, A., "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 8407, DOI 10.17487/RFC8407, October 2018, <https://www.rfc-editor.org/info/rfc8407>.

[RFC8446]

Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.

[RFC8466]

Wen, B., Fioccola, G., Ed., Xie, C., and L. Jalil, "A YANG Data Model for Layer 2 Virtual Private Network (L2VPN) Service Delivery", RFC 8466, DOI 10.17487/RFC8466, October 2018, <https://www.rfc-editor.org/info/rfc8466>.

[RFC8519]

Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, "YANG Data Model for Network Access Control Lists (ACLs)", RFC 8519, DOI 10.17487/RFC8519, March 2019, <https://www.rfc-editor.org/info/rfc8519>.

[RFC8675]

Boucadair, M., Farrer, I., and R. Asati, "A YANG Data Model for Tunnel Interface Types", RFC 8675, DOI 10.17487/RFC8675, November 2019, <https://www.rfc-editor.org/info/rfc8675>.

[RFC8892]

Thaler, D. and D. Romascanu, "Guidelines and Registration Procedures for Interface Types and Tunnel Types", RFC 8892, DOI 10.17487/RFC8892, August 2020, <https://www.rfc-editor.org/info/rfc8892>.

[RFC8969]

Wu, Q., Ed., Boucadair, M., Ed., Lopez, D., Xie, C., and L. Geng, "A Framework for Automating Service and Network Management with YANG", RFC 8969, DOI 10.17487/RFC8969, January 2021, <https://www.rfc-editor.org/info/rfc8969>.

[RFC9000]

Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, May 2021, <https://www.rfc-editor.org/info/rfc9000>.

[RFC9108]

Lhotka, L. and P. Špaček, "YANG Types for DNS Classes and Resource Record Types", RFC 9108, DOI 10.17487/RFC9108, September 2021, <https://www.rfc-editor.org/info/rfc9108>.

[RFC9129]

Yeung, D., Qu, Y., Zhang, Z., Chen, I., and A. Lindem, "YANG Data Model for the OSPF Protocol", RFC 9129, DOI 10.17487/RFC9129, October 2022, <https://www.rfc-editor.org/info/rfc9129>.

[RFC9132]

Boucadair, M., Ed., Shallow, J., and T. Reddy.K, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Specification", RFC 9132, DOI 10.17487/RFC9132, September 2021, <https://www.rfc-editor.org/info/rfc9132>.

[RFC9182]

Barguil, S., Gonzalez de Dios, O., Ed., Boucadair, M., Ed., Munoz, L., and A. Aguado, "A YANG Network Data Model for Layer 3 VPNs", RFC 9182, DOI 10.17487/RFC9182, February 2022, <https://www.rfc-editor.org/info/rfc9182>.

[RFC9195]

Lengyel, B. and B. Claise, "A File Format for YANG Instance Data", RFC 9195, DOI 10.17487/RFC9195, February 2022, <https://www.rfc-editor.org/info/rfc9195>.

[RFC9244]

Boucadair, M., Ed., Reddy.K, T., Ed., Doron, E., Chen, M., and J. Shallow, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry", RFC 9244, DOI 10.17487/RFC9244, June 2022, <https://www.rfc-editor.org/info/rfc9244>.

[RFC9291]

Boucadair, M., Ed., Gonzalez de Dios, O., Ed., Barguil, S., and L. Munoz, "A YANG Network Data Model for Layer 2 VPNs", RFC 9291, DOI 10.17487/RFC9291, September 2022, <https://www.rfc-editor.org/info/rfc9291>.

[RFC9362]

Boucadair, M. and J. Shallow, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Configuration Attributes for Robust Block Transmission", RFC 9362, DOI 10.17487/RFC9362, February 2023, <https://www.rfc-editor.org/info/rfc9362>.

[RFC9637]

Huston, G. and N. Buraglio, "Expanding the IPv6 Documentation Space", RFC 9637, DOI 10.17487/RFC9637, August 2024, <https://www.rfc-editor.org/info/rfc9637>.

[RFC9645]

Watsen, K., "YANG Groupings for TLS Clients and TLS Servers", RFC 9645, DOI 10.17487/RFC9645, October 2024, <https://www.rfc-editor.org/info/rfc9645>.

[RFC9911]

Schönwälder, J., Ed., "Common YANG Data Types", RFC 9911, DOI 10.17487/RFC9911, December 2025, <https://www.rfc-editor.org/info/rfc9911>.

[Style]

"IANA YANG", commit 3a6cb69, December 2021, <https://github.com/llhotka/iana-yang>.