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

• Implemented errata 5693, 5800, 6899, and 7416.¶

• Updated the terminology.¶

• Added a note about notation conventions.¶

• Updated the URL of the IETF authors guidelines.¶

• Updated the guidance so that the "file name" after the <CODE BEGINS> tag is mandatory.¶

• Added code markers for the security template.¶

• Updated the YANG security considerations template to better insist on the key secure transport features.¶

• Added statements that the security template is not required for modules that follow [RFC8791] or [RFC7952].¶

• Added a statement about how to cite the RFCs that are listed in the security template.¶

• Added a template for IANA registrations.¶

• Added a note that folding of the examples should be done as per [RFC8792] conventions.¶

• Added a recommendation about long trees.¶

• Added a recommendation for the use of meaningful prefix values.¶

• Added a note that RFC8792-folding of YANG modules can be used if and only if native YANG features (e.g., break line, "+") are not sufficient.¶

• Added tool validation checks to ensure that YANG modules fit into the line limits of an I-D.¶

• Added tool validation checks of JSON-encoded examples.¶

• Updated many examples to be aligned with the consistent indentation recommendation (internal consistency).¶

• Updated the IANA considerations to encourage registration requests to indicate whether a module is maintained by IANA or not.¶

• Added guidelines for IANA-maintained modules.¶

• Elaborated the guidance for the use of values reserved for documentation in examples.¶

• Recommended the use of "example:" for URI examples.¶

• Added a new section "Defining Standard Tags" (Section 4.28) to echo the guidance in [RFC8819].¶

• Recommended against the use of "case + when" construct in some cases.¶

• Added a discussion about the prefix pattern to use for example modules.¶

• Updated the NMDA guidance in the narrative text to highlight modules that are not NMDA-compliant.¶

• Added a new section about YANG module classification.¶

• Fixed an inconsistency in Section 4.6.2 where the example mentions identities, but uses them without their prefix as per Section 4.6.4.¶

• Fixed an inconsistency in Section 4.6.4 which fails to use "derived-from-or-self()" mentioned back in Section 4.6.2.¶

• Added a new section for modeling abstract data structures.¶

• Added a discussion about "must + error-message" constructs for state data.¶

• Added text about summary of changes in revision statements.¶

• Added a template for IANA-maintained modules.¶

• Updates RFC 6020 to record current IANA practices for registering modules and their revisions.¶

2.1. NETCONF Terms

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

• capabilities¶

• client¶

• operation¶

• server¶

2.2. YANG Terms

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

• data node¶

• module¶

• namespace¶

• submodule¶

• version¶

• YANG¶

• YIN¶

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

2.3. Network Management Datastore Architecture (NMDA) Terms

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

• configuration¶

• conventional configuration datastore¶

• datastore¶

• operational state¶

• operational state datastore¶

2.4. Requirements Notation

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

3.1. Module Copyright

The module "description" statement MUST contain a reference to the latest approved IETF Trust Copyright statement, which is available online at:¶

    <https://trustee.ietf.org/license-info/>

3.2. Code Components

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

The "<CODE BEGINS>" tag 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. If the complete tree diagram for a module becomes long (more than 2 pages, typically), the diagram SHOULD be split into several smaller diagrams (a.k.a subtrees). For the reader's convenience, a subtree should fit within a page. If the complete tree diagram is too long (more than 5 pages, typically) even with groupings unexpanded (Section 2.2 of [RFC8340]), the authors SHOULD NOT include it in the document. A stable pointer to retrieve the full tree MAY be included.¶

The document SHOULD include the following note if the full tree is not included:¶

     -- If no stable pointer to retrieve the tree is included

     The full tree diagram of the module can be generated using,
     e.g., the "pyang" tool. That tree is not included here because
     it is too long (Section 3.4 of [RFCAAAA]). Instead, subtrees
     are provided for the reader's convenience.

     -- If a stable pointer to retrieve the tree is included

     The full tree diagram of the module can be retrieved at
     <stable_url_ref>. That tree is not included here because it is too
     long (Section 3.4 of [RFCAAAA]). Instead, subtrees are provided
     for the reader's convenience.

These guidelines take precedence over the generic guidance in Section 3 of [RFC8340].¶

• The tooling may evolve in the future to provide better rendering of too long trees. This tooling may offer (but not limited to), unfold trees, control of expanded views, ease navigation among various levels of a tree, support of hyperlinks, etc. When such a tooling is available, too long trees can be displayed in the HTML version of documents that include such trees.¶

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

3.5. Narrative Sections

The narrative part MUST include an overview section that describes the scope and field of application of the module(s) defined by the specification and that specifies the relationship (if any) of these modules to other standards, particularly to standards containing other YANG modules. The narrative part SHOULD include one or more sections to briefly describe the structure of the modules defined in the specification.¶

If the module or modules defined by the specification imports definitions from other modules (except for those defined in [RFC7950] or [RFC6991]) or are always implemented in conjunction with other modules, then those facts MUST be noted in the overview section; any special interpretations of definitions in other modules MUST be noted as well. Refer to Section 2.3 of [RFC8349] for an example of this overview section.¶

If the document contains major Network Management Datastore Architecture (NMDA) exceptions or include 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 done for formatting purposes, then this SHOULD be noted following [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>

Native YANG features (e.g., breaking line, "+") SHOULD be used to fit a module into the line limits. Exceptionally, RFC8792-folding of YANG modules MAY be used if and only if native YANG features are not sufficient. A similar approach (e.g., use "--yang-line-length 69" or split 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 YIN syntax version of the module MAY also be present in the document. There MAY also be other types of modules present in the document, such as Structure of Management Information Version 2 (SMIv2), which are not affected by these guidelines.¶

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

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

Consistent indentation and formatting SHOULD be used in all YANG statements within a module.¶

See Section 4 for guidelines on YANG usage.¶

3.7. Security Considerations Section

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

Unless the modules comply with [RFC8791] or define YANG extensions (e.g., [RFC7952]), the security section MUST be patterned after the latest approved template (available at <https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines>). Section 3.7.1 contains the security considerations template. Authors MUST check the web page at the URL listed above in case there is a more recent version available.¶

In particular:¶

• Writable data nodes that could be especially disruptive if abused MUST be explicitly listed by name, and the associated security risks MUST be explained.¶

• Readable data nodes that contain especially sensitive information or that raise significant privacy concerns MUST be explicitly listed by name, and the reasons for the sensitivity/privacy concerns MUST be explained.¶

• Operations (i.e., YANG "rpc" statements) that are potentially harmful to system behavior or that raise significant privacy concerns MUST be explicitly listed by name, and the reasons for the sensitivity/privacy concerns MUST be explained.¶

Documents that define exclusively modules following 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].¶

<CODE BEGINS>


X.  Security Considerations

This section uses the template described in Section 3.7 of [RFCAAAA].

The YANG module specified in this document defines a schema for data
that is designed to be accessed via network management protocols such
as NETCONF [RFC6241] or RESTCONF [RFC8040]. These network management
protocols are required to use a secure transport layer and mutual
authentication, e.g., SSH [RFC6242] without the "none" authentication
option, Transport Layer Security (TLS) [RFC8446] with mutual X.509
authentication, and HTTPS with HTTP authentication (Section 11 of
[RFC9110]).

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.

 -- if you have any writable data nodes (those are all the
 -- "config true" nodes, and remember, that is the default)
 -- describe their specific sensitivity or vulnerability.

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

<list subtrees and data nodes and explain the associated security
 risks with a focus on how they can be disruptive if abused>

 -- for all YANG modules you must evaluate whether any readable data
 -- nodes (those are all the "config false" nodes, but also all other
 -- nodes, because they can also be read via operations like get or
 -- get-config) are sensitive or vulnerable (for instance, if they
 -- might reveal customer information or violate personal privacy
 -- laws such as those of the European Union if exposed to
 -- unauthorized parties)

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

<list subtrees and data nodes and explain the reasons for
 the sensitivity/privacy concerns>

 -- if your YANG module has defined any RPC operations
 -- describe their specific sensitivity or vulnerability.

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

<list RPC operations and explain the reasons for the sensitivity/
 privacy concerns>

   -- if your YANG module 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.

  -- if your YANG module does not define any data nodes, 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').


<CODE ENDS>

3.8. IANA Considerations Section

In order to comply with IESG policy as set forth in <https://www.ietf.org/id-info/checklist.html>, every I-D that is submitted to the IESG for publication MUST contain an IANA Considerations section. The requirements for this section vary depending on what actions are required of the IANA. If there are no IANA considerations applicable to the document, then the IANA Considerations section will state that "This document has no IANA actions". Refer to the guidelines in [RFC8126] for more details.¶

Each normative YANG module MUST be registered in both the "IETF XML Registry" [RFC3688] [IANA-XML] and the "YANG Module Names" registry [RFC6020] [IANA-MOD-NAMES]. The registration request in the "YANG Module Names" registry should indicate whether the module is IANA-maintained or not. 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.¶

A registration template is provided below:¶

   IANA is requested to register the following URI in the "ns"
   subregistry within the "IETF XML Registry" [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" subregistry [RFC6020] within the "YANG Parameters"
   registry.

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

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

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>
  <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 available. The 'rfcstrip' tool that supports YANG module extraction is freely available at:¶

  <https://github.com/mbj4668/rfcstrip>

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

The "xym" tool is freely available on GitHub and can be used to extract YANG modules from a document.¶

   <https://github.com/xym-tool/xym>

3.12. Module Usage Examples

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

• IPv4 and IPv6 addresses/prefixes reserved for documentation are defined in [RFC5737] and [RFC3849].¶

• The Enterprise Number 32473 reserved for documentation use is defined in [RFC5612].¶

• Autonomous System Numbers (ASNs) reserved for documentation use are defined in [RFC5398].¶

• Reserved domain names for documentation are defined in [RFC2606].¶

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

4.1. Module Naming Conventions

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

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

All published module names MUST be unique. For a YANG module published in an RFC, this uniqueness is guaranteed by IANA (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 prefix be selected that represents the entire organization. All normative YANG modules published by the IETF MUST begin with the prefix "ietf-". Another standards organization, such as the IEEE, might use the prefix "ieee-" for all YANG modules.¶

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

4.2. Prefixes

All YANG definitions are scoped by the module containing the definition being referenced. This allows definitions from multiple modules to be used, even if the names are not unique. In the example below, the identifier "foo" is used in all three modules:¶

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

      container foo;
    }

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

      typedef foo { type uint32; }
    }

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

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

YANG defines the following rules for prefix usage:¶

• Prefixes are never used for built-in data types and YANG keywords.¶

• A prefix MUST be used for any external statement (i.e., a statement defined with the YANG "extension" statement).¶

• The proper module prefix MUST be used for all identifiers imported from other modules.¶

• The proper module prefix MUST be used for all identifiers included from a submodule.¶

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

• The local module prefix SHOULD be used instead of no prefix in all path expressions.¶

• The local module prefix MUST be used instead of no prefix in all "default" statements for an "identityref" or "instance-identifier" data type.¶

• The local module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module.¶

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 MAY 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 "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 modelling 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 a provision for defining a constraint on state data and specifies that the constraint must be true in a valid state data. However, Section 5.3 of [RFC8342] softens that behavior by allowing semantic constraints to be violated under some circumstances to help detecting anomalies. Relaxing validation constraints on state data is meant to reveal deviations of the observed behavior vs. 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 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 6991: Common YANG Data Types";
     }

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

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

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

4.8. Module Header, Meta, and Revision Statements

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

The "organization" statement MUST be present. If the module is contained in a document intended for IETF Standards Track status, then the organization SHOULD be the IETF working group (WG) chartered to write the document. For other standards organizations, a similar approach is also suggested.¶

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

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

• All revisions of IETF and IANA published modules can be found at the YANG Parameters registry: 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 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
     "RFC YYYY: 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:¶

• the module to compile correctly instead of generating disruptive fatal errors.¶

• early implementors to use the modules without picking a random value for the XML namespace.¶

• early interoperability testing since independent implementations will use the same XML namespace value.¶

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

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

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

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

Example URIs using URLs per [RFC3986]:¶

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

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

Example URIs using tags per [RFC4151]:¶

    tag:example.com,2017:example-interfaces

    tag:example.com,2017:example-system

4.10. Top-Level Data Definitions

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

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

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 ipv4-address-no-zone {
      type inet:ipv4-address {
        pattern '[0-9\.]*';
      }
      ...
    }

    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 [RFC6991], then it SHOULD be used instead of defining a new derived type.¶

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

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

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

The "description" statement MUST be present.¶

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

4.13. Reusable Groupings

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

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

• Clearly identify the purpose of the grouping in the "description" statement.¶

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

• Do not reference data outside the grouping in any "path", "must", or "when" statements.¶

• Do not include a "default" substatement on a leaf or choice unless the value applies on all possible contexts.¶

• Do not include a "config" substatement on a data node unless the value applies on all possible contexts.¶

• Clearly identify any external dependencies in the grouping "description" statement, such as nodes referenced by an absolute path from a "path", "must", or "when" statement.¶

4.14. Data Definitions

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

• anyxml¶

• augment¶

• choice¶

• container¶

• extension¶

• feature¶

• grouping¶

• identity¶

• leaf¶

• leaf-list¶

• list¶

• notification¶

• rpc¶

• typedef¶

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

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

It has been found that the "anyxml" statement is not implemented consistently across all servers. It is possible that mixed-mode XML will not be supported or that configuration anyxml nodes will not supported.¶

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

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

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

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

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

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

• The semantics of the extension MUST NOT contradict any YANG statements. Extensions can add semantics not covered by the normal YANG statements.¶

• The module containing the extension statement MUST clearly identify the conformance requirements for the extension. It should be clear whether all implementations of the YANG module containing the extension need to also implement the extension. If not, identify what conditions apply that would require implementation of the extension.¶

• The extension MUST clearly identify where it can be used within other YANG statements.¶

• The extension MUST clearly identify if YANG statements or other extensions are allowed or required within the extension as substatements.¶

4.22. Data Correlation

Data can be correlated in 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.com:params:xml:ns:yang:example-foo";
    prefix "foo";

    container foo {
      // configuration data child nodes
      // operational value in operational state datastore only
      // may contain "config false" nodes as needed
    }
 }

  module example-foo {
    namespace "urn:example.com:params:xml:ns:yang:example-foo";
    prefix "foo";

    container foo {
      // configuration data child nodes
    }

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

Converted NMDA Module:

  module example-foo {
    namespace "urn:example.com:params:xml:ns:yang:example-foo";
    prefix "foo";

    container foo {
      // configuration data child nodes
      // operational value in operational state datastore only
      // may contain "config false" nodes as needed
      // will contain any data nodes from old foo-state
    }

    // keep original foo-state but change status to deprecated
    container foo-state {
      config false;
      status deprecated;
      // operational state child nodes
    }
 }

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

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

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

4.24. Performance Considerations

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

• Lists are generally more expensive than containers¶

• "when" statement evaluation is generally more expensive than "if-feature" or "choice" statements¶

• "must" statements are generally more expensive than "min-entries", "max-entries", "mandatory", or "unique" statements¶

• "identityref" leafs are generally more expensive than "enumeration" leafs¶

• "leafref" and "instance-identifier" types with "require-instance" set to "true" are generally more expensive than if "require-instance" is set to "false"¶

4.25. Open Systems Considerations

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

4.26. Guidelines for Constructs Specific to YANG 1.1

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

   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, the RFC document is used for published work, and the 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 module 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 [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 [RFC8791] is RECOMMENDED compared to the "yang-data" extension statement [RFC8040].¶

• Examples of modules that rely upon [RFC8791] are [RFC9132] or [RFC9195].¶

Abstract data structures can be augmented using the "augment-structure" statement [RFC8791].¶

• Examples of modules that augment abstract data structures are [RFC9244] and [RFC9362].¶

4.30. IANA-Maintained Modules

 "The DOTS telemetry module (Section 10.1) uses "enumerations" rather
 than "identities" to define units, samples, and intervals because
 otherwise the namespace identifier "ietf-dots-telemetry" must be
 included when a telemetry attribute is included (e.g., in a
 mitigation efficacy update).  The use of "identities" is thus
 suboptimal from a message compactness standpoint; one of the key
 requirements for DOTS messages."

  Note: [Style] provides XSLT 1.0 stylesheets and other tools for
  translating IANA registries to YANG modules.  The tools can be
  used to generate up-to-date revisions of an IANA-maintained module
  based upon the XML representation of an IANA registry.

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

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

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

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

<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
[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 must 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 sub-
statements 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
existing 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.

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.



<CODE ENDS>

<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
[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 sub-statements 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 must be added in front of the
existing 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.

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.


<CODE ENDS>

5.1. YANG Modules

The following registration in the "ns" subregistry of the "IETF XML Registry" [RFC3688] was detailed in [RFC8407]. This document requests IANA to update 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 is requested to register the following URI in the "ns" subregistry within the "IETF XML Registry" [RFC3688]:¶

   URI:  urn:ietf:params:xml:ns:yang:iana-template
   Registrant Contact:  The IESG.
   XML:  N/A; the requested URI is an XML namespace.

This document requests IANA to register the following YANG modules in the "YANG Module Names" registry [RFC6020] 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 AAAA

   Name:  iana-template
   Maintained by IANA?  N
   Namespace:  urn:ietf:params:xml:ns:yang:iana-template
   Prefix:  iana-foo
   Reference:  RFC AAAA

5.2. Update YANG Parameters Registry

Also, this document requests IANA to update the reference for the "YANG Module Names" registry under the "YANG Parameters" registry group to point to the RFC number that will be assigned to this document as it contains the template necessary for registration in Appendix B.¶

5.3. Revisions of Published Modules

IANA considerations to register YANG module and submodule names are specified in Section 14 of [RFC6020]. This document amends the guidance on names unicity as follows:¶

OLD:

All module and submodule names in the registry MUST be unique.¶

All XML namespaces in the registry MUST be unique.¶

NEW:

Modules and their revisions are maintained in the registry.¶

A module and all its revisions MUST have the same name and namespace.¶

All initial version module and submodule names in the registry MUST be unique.¶

All XML namespaces of initial version modules in the registry MUST be unique.¶

5.4. IANA-Maintained Modules

IANA should refer to Section 4.30.3 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:¶

• When an underlying registration is deprecated or obsoleted, a corresponding "status" substatement should be added to the identity or enumeration statement.¶

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

In addition, when the module is published, IANA must add the following notes to:¶

The YANG Module Names registry:

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

The underlying registry:

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