4.  YANG Usage Guidelines

   Modules in IETF Standards Track specifications MUST comply with all
   syntactic and semantic requirements of YANG 1.1 [RFC7950].  See the
   exception for YANG 1.0 in Section 3.6.  The guidelines in this
   section are intended to supplement the YANG specification [RFC7950],
   which is intended to define a minimum set of conformance
   requirements.

   In order to promote interoperability and establish a set of practices
   based on previous experience, the following sections establish usage
   guidelines for specific YANG constructs.

   Only guidelines that clarify or restrict the minimum conformance
   requirements are included here.

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:

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

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

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

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

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

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

   o  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.3.1.  Identifier Naming Conventions

   Identifiers SHOULD follow a consistent naming pattern throughout the
   module.  Only lowercase letters, numbers, and dashes SHOULD be used
   in identifier names.  Uppercase characters, the period character, and
   the underscore character MAY be used if the identifier represents a
   well-known value that uses these characters.  YANG does not permit
   any other characters in YANG identifiers.

   Identifiers SHOULD include complete words and/or well-known acronyms
   or abbreviations.  Child nodes within a container or list SHOULD NOT
   replicate the parent identifier.  YANG identifiers are hierarchical
   and are only meant to be unique within the set of sibling nodes
   defined in the same module namespace.

   It is permissible to use common identifiers such as "name" or "id" in
   data definition statements, especially if these data nodes share a
   common data type.

   Identifiers SHOULD NOT carry any special semantics that identify data
   modeling properties.  Only YANG statements and YANG extension
   statements are designed to convey machine-readable data modeling
   properties.  For example, naming an object "config" or "state" does

   not change whether it is configuration data or state data.  Only
   defined YANG statements or YANG extension statements can be used to
   assign semantics in a machine-readable format in YANG.

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.

                     +--------------+---------------+
                     | Statement    | Default Value |
                     +--------------+---------------+
                     | config       | true          |
                     | mandatory    | false         |
                     | max-elements | unbounded     |
                     | min-elements | 0             |
                     | ordered-by   | system        |
                     | status       | current       |
                     | yin-element  | false         |
                     +--------------+---------------+

                            Statement Defaults

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.

4.6.1.  XPath Evaluation Contexts

   YANG defines five separate contexts for evaluation of XPath
   statements:

   1.  The "running" datastore: collection of all YANG configuration
       data nodes.  The document root is the conceptual container (e.g.,
       "config" in the "edit-config" operation), which is the parent of
       all top-level data definition statements with a "config"
       statement value of "true".

   2.  State data + the "running" datastore: collection of all YANG data
       nodes.  The document root is the conceptual container, parent of
       all top-level data definition statements.

   3.  Notification: an event notification document.  The document root
       is the notification element.

   4.  RPC Input: The document root is the conceptual "input" node,
       which is the parent of all RPC input parameter definitions.

   5.  RPC Output: The document root is the conceptual "output" node,
       which is the parent of all RPC output parameter definitions.

   Note that these XPath contexts cannot be mixed.  For example, a
   "when" statement in a notification context cannot reference
   configuration data.

       notification foo {
         leaf mtu {
           // NOT okay because when-stmt context is this notification
           when "/if:interfaces/if:interface[name='eth0']";
           type leafref {
             // Okay because path-stmt has a different context
             path "/if:interfaces/if:interface/if:mtu";
           }
         }
       }

   It is especially important to consider the XPath evaluation context
   for XPath expressions defined in groupings.  An XPath expression
   defined in a grouping may not be portable, meaning it cannot be used
   in multiple contexts and produce proper results.

   If the XPath expressions defined in a grouping are intended for a
   particular context, then this context SHOULD be identified in the
   "description" statement for the grouping.

4.6.2.  Function Library

   The "position" and "last" functions SHOULD NOT be used.  This applies
   to implicit use of the "position" function as well (e.g.,
   '//chapter[42]').  A server is only required to maintain the relative
   XML document order of all instances of a particular user-ordered list
   or leaf-list.  The "position" and "last" functions MAY be used if
   they are evaluated in a context where the context node is a user-
   ordered "list" or "leaf-list".

   The "id" function SHOULD NOT be used.  The "ID" attribute is not
   present in YANG documents, so this function has no meaning.  The YANG
   compiler SHOULD return an empty string for this function.

   The "namespace-uri" and "name" functions SHOULD NOT be used.
   Expanded names in XPath are different than YANG.  A specific
   canonical representation of a YANG-expanded name does not exist.

   The "lang" function SHOULD NOT be used.  This function does not apply
   to YANG because there is no "lang" attribute set with the document.
   The YANG compiler SHOULD return 'false' for this function.

   The "local-name", "namespace-uri", "name", "string", and "number"
   functions SHOULD NOT be used if the argument is a node-set.  If so,
   the function result will be determined by the document order of the
   node-set.  Since this order can be different on each server, the
   function results can also be different.  Any function call that
   implicitly converts a node-set to a string will also have this issue.

   The "local-name" function SHOULD NOT be used to reference local names
   outside of the YANG module that defines the must or when expression
   containing the "local-name" function.  Example of a "local-name"
   function that should not be used:

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

   The "derived-from-or-self" function SHOULD be used instead of an
   equality expression for identityref values.  This allows the
   identities to be conceptually augmented.

   Example:

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

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

4.6.3.  Axes

   The "attribute" and "namespace" axes are not supported in YANG and
   MAY be empty in a NETCONF or RESTCONF server implementation.

   The "preceding" and "following" axes SHOULD NOT be used.  These
   constructs rely on XML document order within a NETCONF or RESTCONF
   server configuration database, which may not be supported
   consistently or produce reliable results across implementations.
   Predicate expressions based on static node properties (e.g., element
   name or value, and "ancestor" or "descendant" axes) SHOULD be used
   instead.  The "preceding" and "following" axes MAY be used if
   document order is not relevant to the outcome of the expression
   (e.g., check for global uniqueness of a parameter value).

   The "preceding-sibling" and "following-sibling" axes SHOULD NOT be
   used; however, they MAY be used if document order is not relevant to
   the outcome of the expression.

   A server is only required to maintain the relative XML document order
   of all instances of a particular user-ordered list or leaf-list.  The
   "preceding-sibling" and "following-sibling" axes MAY be used if they
   are evaluated in a context where the context node is a user-ordered
   "list" or "leaf-list".

4.6.4.  Types

   Data nodes that use the "int64" and "uint64" built-in type SHOULD NOT
   be used within numeric or boolean expressions.  There are boundary
   conditions in which the translation from the YANG 64-bit type to an
   XPath number can cause incorrect results.  Specifically, an XPath
   "double" precision floating-point number cannot represent very large
   positive or negative 64-bit numbers because it only provides a total
   precision of 53 bits.  The "int64" and "uint64" data types MAY be
   used in numeric expressions if the value can be represented with no
   more than 53 bits of precision.

   Data modelers need to be careful not to confuse the YANG value space
   and the XPath value space.  The data types are not the same in both,
   and conversion between YANG and XPath data types SHOULD be considered
   carefully.

   Explicit XPath data type conversions MAY be used (e.g., "string",
   "boolean", or "number" functions), instead of implicit XPath data
   type conversions.

   XPath expressions that contain a literal value representing a YANG
   identity SHOULD always include the declared prefix of the module
   where the identity is defined.

   XPath expressions for "when" statements SHOULD NOT reference the
   context node or any descendant nodes of the context node.  They MAY
   reference descendant nodes if the "when" statement is contained
   within an "augment" statement, and the referenced nodes are not
   defined within the "augment" statement.

   Example:

      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
      }

4.6.5.  Wildcards

   It is possible to construct XPath expressions that will evaluate
   differently when combined with several modules within a server
   implementation rather than when evaluated within the single module.
   This is due to augmenting nodes from other modules.

   Wildcard expansion is done within a server against all the nodes from
   all namespaces, so it is possible for a "must" or "when" expression
   that uses the '*' operator to always evaluate to false if processed
   within a single YANG module.  In such cases, the "description"
   statement SHOULD clarify that augmenting objects are expected to
   match the wildcard expansion.

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

4.6.6.  Boolean Expressions

   The YANG "must" and "when" statements use an XPath boolean expression
   to define the test condition for the statement.  It is important to
   specify these expressions in a way that will not cause inadvertent
   changes in the result if the objects referenced in the expression are
   updated in future revisions of the module.

   For example, the leaf "foo2" must exist if the leaf "foo1" is equal
   to "one" or "three":

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

        leaf foo2 {
          // INCORRECT
          must "/f:foo1 != 'two'";
          type string;
        }

        leaf foo2 {
          // CORRECT
          must "/f:foo1 = 'one' or /f:foo1 = 'three'";
          type string;
        }

   In the next revision of the module, leaf "foo1" is extended with a
   new enum named "four":

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

   Now the first XPath expression will allow the enum "four" to be
   accepted in addition to the "one" and "three" enum values.

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 8341: Network Configuration
                     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 8407: Network Configuration Protocol (NETCONF)
                     Access Control Model";
      }

      revision "2012-02-22" {
        description
          "Initial version";
        reference
          "RFC 8341: Network Configuration
                     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:

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

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

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

4.11.1.  Fixed-Value Extensibility

   If the set of values is fixed and the data type contents are
   controlled by a single naming authority, then an enumeration data
   type SHOULD be used.

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

   If extensibility of enumerated values is required, then the
   "identityref" data type SHOULD be used instead of an enumeration or
   other built-in type.

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

   Note that any module can declare an identity with base "foo-type"
   that is valid for the "foo" leaf.  Identityref values are considered
   to be qualified names.

4.11.2.  Patterns and Ranges

   For string data types, if a machine-readable pattern can be defined
   for the desired semantics, then one or more pattern statements SHOULD
   be present.  A single-quoted string SHOULD be used to specify the
   pattern, since a double-quoted string can modify the content.  If the
   patterns used in a type definition have known limitations such as
   false negative or false positive matches, then these limitations
   SHOULD be documented within the typedef or data definition.

   The following typedef from [RFC6991] demonstrates the proper use of
   the "pattern" statement:

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

   For string data types, if the length of the string is required to be
   bounded in all implementations, then a length statement MUST be
   present.

   The following typedef from [RFC6991] demonstrates the proper use of
   the "length" statement:

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

   For numeric data types, if the values allowed by the intended
   semantics are different than those allowed by the unbounded intrinsic
   data type (e.g., "int32"), then a range statement SHOULD be present.

   The following typedef from [RFC6991] demonstrates the proper use of
   the "range" statement:

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

4.11.3.  Enumerations and Bits

   For "enumeration" or "bits" data types, the semantics for each "enum"
   or "bit" SHOULD be documented.  A separate "description" statement
   (within each "enum" or "bit" statement) SHOULD be present.

       leaf foo {
         // INCORRECT
         type enumeration {
           enum one;
           enum two;
         }
         description
           "The foo enum...
            one: The first enum
            two: The second enum";
       }

       leaf foo {
         // CORRECT
         type enumeration {
           enum one {
             description "The first enum";
           }
           enum two {
             description "The second enum";
           }
         }
         description
           "The foo enum...  ";
       }

4.11.4.  Union Types

   The YANG "union" type is evaluated by testing a value against each
   member type in the union.  The first type definition that accepts a
   value as valid is the member type used.  In general, member types
   SHOULD be ordered from most restrictive to least restrictive types.

   In the following example, the "enumeration" type will never be
   matched because the preceding "string" type will match everything.

   Incorrect:

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

   Correct:

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

   It is possible for different member types to match, depending on the
   input encoding format.  In XML, all values are passed as string
   nodes; but in JSON, there are different value types for numbers,
   booleans, and strings.

   In the following example, a JSON numeric value will always be matched
   by the "int32" type, but in XML the string value representing a
   number will be matched by the "string" type.  The second version will
   match the "int32" member type no matter how the input is encoded.

   Incorrect:

      type union {
        type string;
        type int32;
      }

   Correct:

      type union {
        type int32;
        type string;
      }

4.11.5.  Empty and Boolean

   YANG provides an "empty" data type, which has one value (i.e.,
   present).  The default is "not present", which is not actually a
   value.  When used within a list key, only one value can (and must)
   exist for this key leaf.  The type "empty" SHOULD NOT be used for a
   key leaf since it is pointless.

   There is really no difference between a leaf of type "empty" and a
   leaf-list of type "empty".  Both are limited to one instance.  The
   type "empty" SHOULD NOT be used for a leaf-list.

   The advantage of using type "empty" instead of type "boolean" is that
   the default (not present) does not take up any bytes in a
   representation.  The disadvantage is that the client may not be sure
   if an empty leaf is missing because it was filtered somehow or not
   implemented.  The client may not have a complete and accurate schema
   for the data returned by the server and may not be aware of the
   missing leaf.

   The YANG "boolean" data type provides two values ("true" and
   "false").  When used within a list key, two entries can exist for
   this key leaf.  Default values are ignored for key leafs, but a
   default statement is often used for plain boolean leafs.  The
   advantage of the "boolean" type is that the leaf or leaf-list has a
   clear representation for both values.  The default value is usually
   not returned unless explicitly requested by the client, so no bytes
   are used in a typical representation.

   In general, the "boolean" data type SHOULD be used instead of the
   "empty" data type, as shown in the example below:

   Incorrect:

      leaf flag1 {
        type empty;
      }

   Correct:

      leaf flag2 {
        type boolean;
        default false;
      }

4.12.  Reusable Type Definitions

   If an appropriate derived type exists in any standard module, such as
   [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:

   o  Clearly identify the purpose of the grouping in the "description"
      statement.

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

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

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

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

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