What does YANG 'identity' mean?

I've worked with YANG on a fairly basic level for quite some time and just recently stumbled across the 'identity' statement found in iana-if-types2@014-05-08.yang as an example.

According to RFC6020

The "identity" statement is used to define a new globally unique, abstract, and untyped identity. Its only purpose is to denote its name, semantics, and existence.

What does this actually mean? I read this as its only purpose is to just... be there. Clearly this can't be the case so what am I missing?

How is the 'identity' statement used in the real world, what does it represent? Can I make references using this identity somehow or is it just documentation?

I searched the YangModels/yang repo for usages of a particular identity and I still can't tell what the purpose of this statement is.

Solution

The purpose of this statement is to define the value space for a built-in YANG type called identityref. Each value of this value space is a name qualified with the namespace of the defining module. If we name an identity foobar and define it within a module with namespace foobar:uri, this produces a value like {foobar:uri}foobar in Clark notation (assuming XML encoding of data). The meaning (semantics) of the name is left for data modelers to define. It can be anything and is defined in human language (descriptions).

The statement is used to create a "tree" of such values, where the relation between the nodes is "derived from" and is expressed using the optional base child statement. The relation goes in a single direction (there can be no cycles). While RFC6020 (YANG version 1) does not support "multiple derivation" (multiple bases), RFC7950 (YANG version 1.1) does.

The "tree" of values may be "expanded" by other modules that import an identity and use it as a base for a new identity they define. Obviously, the whole "tree" may be defined within a single module, without ever importing anything. The takeaway here is that a definition of an identity is not necessarily "tightly coupled" to identities that are derived from it, only the other way around. This makes it possible to define an identity before knowing what the "final form" of the value "tree" based on it will look like. If fact, the "tree" may be different for each implementation, depending on the module set used in it.

There are examples in the RFC6020, Section 7.16.3.:

     module crypto-base {
         namespace "http://example.com/crypto-base";
         prefix "crypto";

         identity crypto-alg {
             description
                "Base identity from which all crypto algorithms
                 are derived.";
         }
     }

     module des {
         namespace "http://example.com/des";
         prefix "des";

         import "crypto-base" {
             prefix "crypto";
         }

         identity des {
             base "crypto:crypto-alg";
             description "DES crypto algorithm";
         }

         identity des3 {
             base "crypto:crypto-alg";
             description "Triple DES crypto algorithm";
         }
     }

The example creates the following "tree" of values:

crypto:crypto-alg
 |- des:des
 |- des:des3

Both des:des and des:des3 values are derived from crypto:crypto-alg value. You use those by creating a leaf/leaf-list/typedef of type identityref and picking the root (or one of the branches) of said tree for its base:

// ...
namespace "uri:foo";
import crypto-base {prefix crypto;}

leaf foo {
  type identityref {
    base crypto:crypto-alg;
  }
}

With YANG version 1, the valid values for this leaf are (assuming XML encoding and Clark notation): {http://example.com/crypto-base}crypto-alg, {http://example.com/des}des, {http://example.com/des}des3. This changed with YANG version 1.1, where the relation between the "tree" values is further clarified to have the following properties: it is irreflexive and transitive; only {http://example.com/des}des, {http://example.com/des}des3 are valid values for the leaf there.

So in this example the identities are used to define cryptographic algorithms. It is clear from the definitions that those three names are "related" to each other and how.

Note: it is unusual to express these values in Clark notation in YANG world. Usually, you'll encounter these in prefix:identity-name notation, where the prefix is a name bound to a namespace depending on some context, or simply a module name. I used both notations. In some contexts, only the identity-name is sufficient to uniquely identify the referenced identity.