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.¶
• Updated the URL of the IETF authors guidelines.¶
• Added code markers for the security template.¶
• Updated the YANG security considerations template to reflect the latest version maintained in the Wiki.¶
• Added statements that the security template is not required for modules that follow [RFC8791].¶
• Added a statement that the RFCs that are listed in the security template are to be listed as normative references in documents that use the template.¶
• Added a note that folding of the examples should be done as per [RFC8792] conventions.¶
• 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.¶
• 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.¶

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. 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 SHOULD be followed by a string identifying the file name specified in Section 5.2 of [RFC7950]. The name string form that includes the revision date SHOULD be used. The revision date MUST match the date used in the most recent revision of the module.¶

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

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

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

3.5. Narrative Sections

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

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

If the document contains a YANG module(s) that is compliant with NMDA [RFC8342], then the Introduction section should mention this fact.¶

Example:

The YANG data model in this document conforms to the Network Management Datastore Architecture defined in [RFC8342].¶

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

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], 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 dated 2013-05-08 and last updated on 2018-10-18. 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.¶

<CODE BEGINS>

X.  Security Considerations

The YANG module specified in this document defines a schema for data
that is designed to be accessed via network management protocols such
as NETCONF [RFC6241] or RESTCONF [RFC8040].  The lowest NETCONF layer
is the secure transport layer, and the mandatory-to-implement secure
transport is Secure Shell (SSH) [RFC6242].  The lowest RESTCONF layer
is HTTPS, and the mandatory-to-implement secure transport is TLS
[RFC8446].

The 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.
These are the subtrees and data nodes and their sensitivity/
vulnerability:

<list subtrees and data nodes and state why they are sensitive>

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

Some of the readable data nodes in this YANG module may be considered
sensitive or vulnerable in some network environments.  It is thus
important to control read access (e.g., via get, get-config, or
notification) to these data nodes.  These are the subtrees and data
nodes and their sensitivity/vulnerability:

<list subtrees and data nodes and state why they are sensitive>

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

Some of the RPC operations in this YANG module may be considered
sensitive or vulnerable in some network environments.  It is thus
important to control access to these operations.  These are the
operations and their sensitivity/vulnerability:

<list RPC operations and state why they are sensitive>


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

Additional IANA considerations applicable to IANA-maintained modules are provided in Section 5.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, "yangson" program should be used. The "yangson" program is freely available from GitHub.¶

  <https://github.com/CZ-NIC/yangson>

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 are used, then a mix of either IPv4 and IPv6 addresses or IPv6 addresses exclusively SHOULD be used in the examples. IPv4 and IPv6 addresses/prefixes reserved for documentation are defined [RFC5737] and [RFC3849].¶

4.1. Module Naming Conventions

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

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

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

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

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

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

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 are also likely to be unique. Prefix values SHOULD NOT conflict with known modules that have been previously published.¶

4.3. Identifiers

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

4.4. Defaults

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

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

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']

   // do not use
   when "md-name-format = 'name-format-null'";

   // this is preferred
   when "derived-from-or-self(md-name-format, 'name-format-null')";

   augment "/rt:active-route/rt:input/rt:destination-address" {
     when "rt:address-family='v4ur:ipv4-unicast'" {
       description
         "This augment is valid only for IPv4 unicast.";
     }
     // nodes defined here within the augment-stmt
     // cannot be referenced in the when-stmt
   }

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

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

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

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

   revision "2012-02-22" {
     description
       "Initial version";
     reference
       "RFC 6536: Network Configuration Protocol (NETCONF)
                  Access Control Model";
   }

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

The following example shows the two revision statements for an unpublished update to a published YANG module:¶

   revision "2017-12-11" {
     description
       "Added support for YANG 1.1 actions and notifications tied to
        data nodes. Clarify how NACM extensions can be used by other
        data models.";
     reference
       "RFC YYYY: Network Configuration Access Control Model";
   }

   revision "2012-02-22" {
     description
       "Initial version";
     reference
       "RFC 6536: Network Configuration Protocol (NETCONF)
                  Access Control Model";
   }

4.9. Namespace Assignments

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

• 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 RFC 7950, Section 7.20.3, the YANG "deviation" statement is not allowed to appear in IETF YANG modules, but it can be useful for documenting server capabilities. Deviation statements are not reusable and typically not shared across all platforms.¶

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

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 new NMDA [RFC8342] and conceptually contained in the operational state datastore, which also includes the operational values of configuration data. There is no longer any need to duplicate data structures to provide separate configuration and operational state sections.¶

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

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

5.1. Context

IANA maintains a set of registries that are key for interoperability. The content of these registries are usually available using various formats (e.g., plain text, XML). However, there were some confusion in the past about whether the content of some registries is dependent on a specific representation format. For example, Section 5 of [RFC8892] was published to clarify that MIB and YANG modules are merely additional formats in which the "Interface Types (ifType)" and "Tunnel Types (tunnelType)" registries are available. The MIB [RFC2863] and YANG modules [RFC7224][RFC8675] are not separate registries, and the same values are always present in all formats of the same registry.¶

Also, some YANG modules include parameters and values directly in a module that is not maintained by IANA while these are populated in an IANA registry. Such a design is suboptimal as it creates another source of information that may deviate from the IANA registry as new values are assigned or some values are deprecated.¶

For the sake of consistency, better flexibility to support new values, and maintaining IANA registries as the unique authoritative source of information, when such an information is maintained in a registry, this document encourages the use of IANA-maintained modules.¶

The following section provides a set of guidelines for YANG module authors related to the design of IANA-maintained modules. These guidelines are meant to leverage existing IANA registries and use YANG as another format to present the content of these registries when appropriate.¶

5.2. Guidelines for IANA-Maintained Modules

When designing a YANG module for a functionality governed by a protocol for which IANA maintains a registry, it is RECOMMENDED to specify an IANA-maintained module that echoes the content of that registry. This is superior to including that content in an IETF- maintained module.¶

When one or multiple sub-registries are available under the same registry, it is RECOMMENDED to define an IANA-maintained module for each sub-registry. However, module designers MAY consider defining one single IANA-maintained module that covers all sub-registries if maintaining that single module is manageable (e.g., very few values are present or expected to be present for each sub-registry). An example of such a module is documented in Section 5.2 of [RFC9132].¶

An IANA-maintained module may use identities (e.g., [RFC8675]) or enumerations (e.g., [RFC9108]). The decision about which type to use is left to the module designers and should be made based upon specifics related to the intended use of the IANA-maintained module. For example, identities are useful if the registry entries are organized hierarchically, possibly including multiple inheritances. It is RECOMMENDED that the reasoning for the design choice is documented in the companion specification that registers an IANA- maintained module. For example, [RFC9244] defines an IANA-maintained module that uses enumerations for the following reason:¶

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

Designers of IANA-maintained modules MAY supply the full initial version of the module in a specification document that registers the module or only a script to be used (including by IANA) for generating the module (e.g., an XSLT stylesheet as in Appendix A of [RFC9108]). For both cases, the document that defines an IANA-maintained module MUST include a note indicating that the document is only documenting the initial version of the module and that the authoritative version is to be retrieved from the IANA registry. It is RECOMMENDED to include the URL from where to retrieve the recent version of the module. When a script is used, the Internet-Draft that defines an IANA-maintained module SHOULD include an appendix with the initial full version of the module. Including such an appendix in pre-RFC versions is meant to assess the correctness of the outcome of the supplied script. The authors MUST include a note to the RFC Editor requesting that the appendix be removed before publication as RFC. Initial versions of IANA-maintained modules that are published in RFCs may be misused despite the appropriate language to refer to the IANA registry to retrieve the up-to-date module. This is problematic for interoperability, e.g., when values are deprecated or are associated with a new meaning.¶

  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.

If an IANA-maintained module is imported by another module, a normative reference with the IANA URL from where to retrieve the IANA-maintained module SHOULD be included. Although not encouraged, referencing the RFC that defines the initial version of the IANA module is acceptable in specific cases (e.g., the imported version is specifically the initial version, the RFC includes useful description about the usage of the module).¶

Examples of IANA URLs from where to retrieve the latest version of an IANA-maintained module are: [IANA_BGP-L2_URL], [IANA_PW-Types_URL], and [IANA_BFD_URL]. [IANA_FOO_URL] is used in the following to refer to such URLs. These URLs are expected to be sufficiently permanent and stable.¶

5.3. Guidance for Writing the IANA Considerations for RFCs Defining IANA-Maintained Modules

In addition to the IANA considerations in Section 3.8, the IANA Considerations Section of an RFC that includes an IANA- maintained module MUST provide the required instructions for IANA to automatically perform the maintenance of that IANA module. These instructions describe how to proceed with updates to the IANA- maintained module that are triggered by a change to the authoritative registry. Concretely, the IANA Considerations Section SHALL at least provide the following information:¶

• An IANA request to add a note to the page displaying the information about the IANA-maintained module that new values must not be directly added to the module, but to an authoritative IANA registry.¶
• An IANA request to add a note to the authoritative IANA registry to indicate that any change to the registry must be reflected into the corresponding IANA-maintained module.¶
• Details about the required actions (e.g., add a new "identity" or "enum" statement) to update the IANA-maintained module to reflect changes to an authoritative IANA registry. Typically, these details have to include the procedure to create a new "identity" statement name and sub-statements ("base", "status", "description", and "reference") or a new "enum" statement and sub- statements ("value", "status", "description", and "reference").¶
• A note that unassigned or reserved values must not be present in the IANA-maintained module.¶
• An indication whether experimental values are included in the IANA-maintained module. Absent such an indication, experimental values MUST NOT be listed in the IANA-maintained module.¶
• An instruction about how to generate the "revision" statement.¶

A template for the IANA Considerations is provided in Section 5.3.1 for IANA-maintained modules with identities and Section 5.3.2 for IANA- maintained modules with enumerations. Authors may modify the template to reflect specifics of their modules (e.g., Multiple registries can be listed for a single IANA-maintained module, no explicit description (or name) field is listed under the authoritative IANA registry).¶

The following templates are to be considered in addition to the required information that is provided in Section 3.8.¶

<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" is the lower-case of the name 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.

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


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

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


<CODE ENDS>