in Index   Prev   Next

RFC 6020

YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

Pages: 173
Proposed Standard
Part 2 of 7 – Pages 11 to 34
First   Prev   Next

Top   ToC   RFC6020 - Page 11   prevText

4. YANG Overview

4.1. Functional Overview

YANG is a language used to model data for the NETCONF protocol. A YANG module defines a hierarchy of data that can be used for NETCONF- based operations, including configuration, state data, Remote Procedure Calls (RPCs), and notifications. This allows a complete description of all data sent between a NETCONF client and server. YANG models the hierarchical organization of data as a tree in which each node has a name, and either a value or a set of child nodes. YANG provides clear and concise descriptions of the nodes, as well as the interaction between those nodes. YANG structures data models into modules and submodules. A module can import data from other external modules, and include data from submodules. The hierarchy can be augmented, allowing one module to add data nodes to the hierarchy defined in another module. This augmentation can be conditional, with new nodes appearing only if certain conditions are met. YANG models can describe constraints to be enforced on the data, restricting the appearance or value of nodes based on the presence or value of other nodes in the hierarchy. These constraints are enforceable by either the client or the server, and valid content MUST abide by them. YANG defines a set of built-in types, and has a type mechanism through which additional types may be defined. Derived types can restrict their base type's set of valid values using mechanisms like range or pattern restrictions that can be enforced by clients or servers. They can also define usage conventions for use of the derived type, such as a string-based type that contains a host name. YANG permits the definition of reusable groupings of nodes. The instantiation of these groupings can refine or augment the nodes, allowing it to tailor the nodes to its particular needs. Derived types and groupings can be defined in one module or submodule and used in either that location or in another module or submodule that imports or includes it.
Top   ToC   RFC6020 - Page 12
   YANG data hierarchy constructs include defining lists where list
   entries are identified by keys that distinguish them from each other.
   Such lists may be defined as either sorted by user or automatically
   sorted by the system.  For user-sorted lists, operations are defined
   for manipulating the order of the list entries.

   YANG modules can be translated into an equivalent XML syntax called
   YANG Independent Notation (YIN) (Section 11), allowing applications
   using XML parsers and Extensible Stylesheet Language Transformations
   (XSLT) scripts to operate on the models.  The conversion from YANG to
   YIN is lossless, so content in YIN can be round-tripped back into

   YANG strikes a balance between high-level data modeling and low-level
   bits-on-the-wire encoding.  The reader of a YANG module can see the
   high-level view of the data model while understanding how the data
   will be encoded in NETCONF operations.

   YANG is an extensible language, allowing extension statements to be
   defined by standards bodies, vendors, and individuals.  The statement
   syntax allows these extensions to coexist with standard YANG
   statements in a natural way, while extensions in a YANG module stand
   out sufficiently for the reader to notice them.

   YANG resists the tendency to solve all possible problems, limiting
   the problem space to allow expression of NETCONF data models, not
   arbitrary XML documents or arbitrary data models.  The data models
   described by YANG are designed to be easily operated upon by NETCONF

   To the extent possible, YANG maintains compatibility with Simple
   Network Management Protocol's (SNMP's) SMIv2 (Structure of Management
   Information version 2 [RFC2578], [RFC2579]).  SMIv2-based MIB modules
   can be automatically translated into YANG modules for read-only
   access.  However, YANG is not concerned with reverse translation from
   YANG to SMIv2.

   Like NETCONF, YANG targets smooth integration with the device's
   native management infrastructure.  This allows implementations to
   leverage their existing access control mechanisms to protect or
   expose elements of the data model.
Top   ToC   RFC6020 - Page 13

4.2. Language Overview

This section introduces some important constructs used in YANG that will aid in the understanding of the language specifics in later sections. This progressive approach handles the inter-related nature of YANG concepts and statements. A detailed description of YANG statements and syntax begins in Section 7.

4.2.1. Modules and Submodules

A module contains three types of statements: module-header statements, revision statements, and definition statements. The module header statements describe the module and give information about the module itself, the revision statements give information about the history of the module, and the definition statements are the body of the module where the data model is defined. A NETCONF server may implement a number of modules, allowing multiple views of the same data, or multiple views of disjoint subsections of the device's data. Alternatively, the server may implement only one module that defines all available data. A module may be divided into submodules, based on the needs of the module owner. The external view remains that of a single module, regardless of the presence or size of its submodules. The "include" statement allows a module or submodule to reference material in submodules, and the "import" statement allows references to material defined in other modules.

4.2.2. Data Modeling Basics

YANG defines four types of nodes for data modeling. In each of the following subsections, the example shows the YANG syntax as well as a corresponding NETCONF XML representation. Leaf Nodes
A leaf node contains simple data like an integer or a string. It has exactly one value of a particular type and no child nodes. YANG Example: leaf host-name { type string; description "Hostname for this system"; }
Top   ToC   RFC6020 - Page 14
   NETCONF XML Example:


   The "leaf" statement is covered in Section 7.6. Leaf-List Nodes
A leaf-list is a sequence of leaf nodes with exactly one value of a particular type per leaf. YANG Example: leaf-list domain-search { type string; description "List of domain names to search"; } NETCONF XML Example: <domain-search></domain-search> <domain-search></domain-search> <domain-search></domain-search> The "leaf-list" statement is covered in Section 7.7. Container Nodes
A container node is used to group related nodes in a subtree. A container has only child nodes and no value. A container may contain any number of child nodes of any type (including leafs, lists, containers, and leaf-lists). YANG Example: container system { container login { leaf message { type string; description "Message given at start of login session"; } } }
Top   ToC   RFC6020 - Page 15
   NETCONF XML Example:

         <message>Good morning</message>

   The "container" statement is covered in Section 7.5. List Nodes
A list defines a sequence of list entries. Each entry is like a structure or a record instance, and is uniquely identified by the values of its key leafs. A list can define multiple key leafs and may contain any number of child nodes of any type (including leafs, lists, containers etc.). YANG Example: list user { key "name"; leaf name { type string; } leaf full-name { type string; } leaf class { type string; } }
Top   ToC   RFC6020 - Page 16
   NETCONF XML Example:

       <full-name>Goldie Locks</full-name>
       <full-name>Snow White</full-name>
       <full-name>Rapun Zell</full-name>

   The "list" statement is covered in Section 7.8. Example Module
These statements are combined to define the module:
Top   ToC   RFC6020 - Page 17
     // Contents of "acme-system.yang"
     module acme-system {
         namespace "";
         prefix "acme";

         organization "ACME Inc.";
         contact "";
             "The module for entities implementing the ACME system.";

         revision 2007-06-09 {
             description "Initial revision.";

         container system {
             leaf host-name {
                 type string;
                 description "Hostname for this system";

             leaf-list domain-search {
                 type string;
                 description "List of domain names to search";

             container login {
                 leaf message {
                     type string;
                         "Message given at start of login session";

                 list user {
                     key "name";
                     leaf name {
                         type string;
                     leaf full-name {
                         type string;
                     leaf class {
                         type string;
Top   ToC   RFC6020 - Page 18

4.2.3. State Data

YANG can model state data, as well as configuration data, based on the "config" statement. When a node is tagged with "config false", its subhierarchy is flagged as state data, to be reported using NETCONF's <get> operation, not the <get-config> operation. Parent containers, lists, and key leafs are reported also, giving the context for the state data. In this example, two leafs are defined for each interface, a configured speed and an observed speed. The observed speed is not configuration, so it can be returned with NETCONF <get> operations, but not with <get-config> operations. The observed speed is not configuration data, and it cannot be manipulated using <edit-config>. list interface { key "name"; leaf name { type string; } leaf speed { type enumeration { enum 10m; enum 100m; enum auto; } } leaf observed-speed { type uint32; config false; } }

4.2.4. Built-In Types

YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special requirements from the management domain. The following table summarizes the built-in types discussed in Section 9:
Top   ToC   RFC6020 - Page 19
       | Name                | Description                         |
       | binary              | Any binary data                     |
       | bits                | A set of bits or flags              |
       | boolean             | "true" or "false"                   |
       | decimal64           | 64-bit signed decimal number        |
       | empty               | A leaf that does not have any value |
       | enumeration         | Enumerated strings                  |
       | identityref         | A reference to an abstract identity |
       | instance-identifier | References a data tree node         |
       | int8                | 8-bit signed integer                |
       | int16               | 16-bit signed integer               |
       | int32               | 32-bit signed integer               |
       | int64               | 64-bit signed integer               |
       | leafref             | A reference to a leaf instance      |
       | string              | Human-readable string               |
       | uint8               | 8-bit unsigned integer              |
       | uint16              | 16-bit unsigned integer             |
       | uint32              | 32-bit unsigned integer             |
       | uint64              | 64-bit unsigned integer             |
       | union               | Choice of member types              |

   The "type" statement is covered in Section 7.4.

4.2.5. Derived Types (typedef)

YANG can define derived types from base types using the "typedef" statement. A base type can be either a built-in type or a derived type, allowing a hierarchy of derived types. A derived type can be used as the argument for the "type" statement. YANG Example: typedef percent { type uint8 { range "0 .. 100"; } description "Percentage"; } leaf completed { type percent; }
Top   ToC   RFC6020 - Page 20
   NETCONF XML Example:


   The "typedef" statement is covered in Section 7.3.

4.2.6. Reusable Node Groups (grouping)

Groups of nodes can be assembled into reusable collections using the "grouping" statement. A grouping defines a set of nodes that are instantiated with the "uses" statement: grouping target { leaf address { type inet:ip-address; description "Target IP address"; } leaf port { type inet:port-number; description "Target port number"; } } container peer { container destination { uses target; } } NETCONF XML Example: <peer> <destination> <address></address> <port>830</port> </destination> </peer> The grouping can be refined as it is used, allowing certain statements to be overridden. In this example, the description is refined:
Top   ToC   RFC6020 - Page 21
     container connection {
         container source {
             uses target {
                 refine "address" {
                     description "Source IP address";
                 refine "port" {
                     description "Source port number";
         container destination {
             uses target {
                 refine "address" {
                     description "Destination IP address";
                 refine "port" {
                     description "Destination port number";

   The "grouping" statement is covered in Section 7.11.

4.2.7. Choices

YANG allows the data model to segregate incompatible nodes into distinct choices using the "choice" and "case" statements. The "choice" statement contains a set of "case" statements that define sets of schema nodes that cannot appear together. Each "case" may contain multiple nodes, but each node may appear in only one "case" under a "choice". When an element from one case is created, all elements from all other cases are implicitly deleted. The device handles the enforcement of the constraint, preventing incompatibilities from existing in the configuration. The choice and case nodes appear only in the schema tree, not in the data tree or NETCONF messages. The additional levels of hierarchy are not needed beyond the conceptual schema.
Top   ToC   RFC6020 - Page 22
   YANG Example:

     container food {
       choice snack {
           case sports-arena {
               leaf pretzel {
                   type empty;
               leaf beer {
                   type empty;
           case late-night {
               leaf chocolate {
                   type enumeration {
                       enum dark;
                       enum milk;
                       enum first-available;

   NETCONF XML Example:


   The "choice" statement is covered in Section 7.9.

4.2.8. Extending Data Models (augment)

YANG allows a module to insert additional nodes into data models, including both the current module (and its submodules) or an external module. This is useful for example for vendors to add vendor- specific parameters to standard data models in an interoperable way. The "augment" statement defines the location in the data model hierarchy where new nodes are inserted, and the "when" statement defines the conditions when the new nodes are valid.
Top   ToC   RFC6020 - Page 23
   YANG Example:

     augment /system/login/user {
         when "class != 'wheel'";
         leaf uid {
             type uint16 {
                 range "1000 .. 30000";

   This example defines a "uid" node that only is valid when the user's
   "class" is not "wheel".

   If a module augments another module, the XML representation of the
   data will reflect the prefix of the augmenting module.  For example,
   if the above augmentation were in a module with prefix "other", the
   XML would look like:

   NETCONF XML Example:

       <full-name>Alice N. Wonderland</full-name>

   The "augment" statement is covered in Section 7.15.

4.2.9. RPC Definitions

YANG allows the definition of NETCONF RPCs. The operations' names, input parameters, and output parameters are modeled using YANG data definition statements.
Top   ToC   RFC6020 - Page 24
   YANG Example:

     rpc activate-software-image {
         input {
             leaf image-name {
                 type string;
         output {
             leaf status {
                 type string;

   NETCONF XML Example:

     <rpc message-id="101"
       <activate-software-image xmlns="">

     <rpc-reply message-id="101"
       <status xmlns="">
         The image acmefw-2.3 is being installed.

   The "rpc" statement is covered in Section 7.13.

4.2.10. Notification Definitions

YANG allows the definition of notifications suitable for NETCONF. YANG data definition statements are used to model the content of the notification.
Top   ToC   RFC6020 - Page 25
   YANG Example:

     notification link-failure {
         description "A link failure has been detected";
         leaf if-name {
             type leafref {
                 path "/interface/name";
         leaf if-admin-status {
             type admin-status;
         leaf if-oper-status {
             type oper-status;

   NETCONF XML Example:

       <link-failure xmlns="">

   The "notification" statement is covered in Section 7.14.

5. Language Concepts

5.1. Modules and Submodules

The module is the base unit of definition in YANG. A module defines a single data model. A module can define a complete, cohesive model, or augment an existing data model with additional nodes. Submodules are partial modules that contribute definitions to a module. A module may include any number of submodules, but each submodule may belong to only one module. The names of all standard modules and submodules MUST be unique. Developers of enterprise modules are RECOMMENDED to choose names for their modules that will have a low probability of colliding with standard or other enterprise modules, e.g., by using the enterprise or organization name as a prefix for the module name.
Top   ToC   RFC6020 - Page 26
   A module uses the "include" statement to include its submodules, and
   the "import" statement to reference external modules.  Similarly, a
   submodule uses the "import" statement to reference other modules, and
   uses the "include" statement to reference other submodules within its
   module.  A module or submodule MUST NOT include submodules from other
   modules, and a submodule MUST NOT import its own module.

   The import and include statements are used to make definitions
   available to other modules and submodules:

   o  For a module or submodule to reference definitions in an external
      module, the external module MUST be imported.

   o  For a module to reference definitions in one of its submodules,
      the module MUST include the submodule.

   o  For a submodule to reference definitions in a second submodule of
      the same module, the first submodule MUST include the second

   There MUST NOT be any circular chains of imports or includes.  For
   example, if submodule "a" includes submodule "b", "b" cannot include

   When a definition in an external module is referenced, a locally
   defined prefix MUST be used, followed by ":", and then the external
   identifier.  References to definitions in the local module MAY use
   the prefix notation.  Since built-in data types do not belong to any
   module and have no prefix, references to built-in data types (e.g.,
   int32) cannot use the prefix notation.

5.1.1. Import and Include by Revision

Published modules evolve independently over time. In order to allow for this evolution, modules need to be imported using specific revisions. When a module is written, it uses the current revisions of other modules, based on what is available at the time. As future revisions of the imported modules are published, the importing module is unaffected and its contents are unchanged. When the author of the module is prepared to move to the most recently published revision of an imported module, the module is republished with an updated "import" statement. By republishing with the new revision, the authors explicitly indicate their acceptance of any changes in the imported module.
Top   ToC   RFC6020 - Page 27
   For submodules, the issue is related but simpler.  A module or
   submodule that includes submodules needs to specify the revision of
   the included submodules.  If a submodule changes, any module or
   submodule that includes it needs to be updated.

   For example, module "b" imports module "a".

     module a {
         revision 2008-01-01 { ... }
         grouping a {
             leaf eh { .... }

     module b {
         import a {
             prefix p;
             revision-date 2008-01-01;

         container bee {
             uses p:a;

   When the author of "a" publishes a new revision, the changes may not
   be acceptable to the author of "b".  If the new revision is
   acceptable, the author of "b" can republish with an updated revision
   in the "import" statement.

5.1.2. Module Hierarchies

YANG allows modeling of data in multiple hierarchies, where data may have more than one top-level node. Models that have multiple top- level nodes are sometimes convenient, and are supported by YANG. NETCONF is capable of carrying any XML content as the payload in the <config> and <data> elements. The top-level nodes of YANG modules are encoded as child elements, in any order, within these elements. This encapsulation guarantees that the corresponding NETCONF messages are always well-formed XML documents.
Top   ToC   RFC6020 - Page 28
   For example:

     module my-config {
         namespace "";
         prefix "co";

         container system { ... }
         container routing { ... }

   could be encoded in NETCONF as:

     <rpc message-id="101"
           <system xmlns="">
             <!-- system data here -->
           <routing xmlns="">
             <!-- routing data here -->

5.2. File Layout

YANG modules and submodules are typically stored in files, one module or submodule per file. The name of the file SHOULD be of the form: module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) YANG compilers can find imported modules and included submodules via this convention. While the YANG language defines modules, tools may compile submodules independently for performance and manageability reasons. Errors and warnings that cannot be detected during submodule compilation may be delayed until the submodules are linked into a cohesive module.
Top   ToC   RFC6020 - Page 29

5.3. XML Namespaces

All YANG definitions are specified within a module that is bound to a particular XML namespace [XML-NAMES], which is a globally unique URI [RFC3986]. A NETCONF client or server uses the namespace during XML encoding of data. Namespaces for modules published in RFC streams [RFC4844] MUST be assigned by IANA, see Section 14. Namespaces for private modules are assigned by the organization owning the module without a central registry. Namespace URIs MUST be chosen so they cannot collide with standard or other enterprise namespaces, for example by using the enterprise or organization name in the namespace. The "namespace" statement is covered in Section 7.1.3.

5.3.1. YANG XML Namespace

YANG defines an XML namespace for NETCONF <edit-config> operations and <error-info> content. The name of this namespace is "urn:ietf:params:xml:ns:yang:1".

5.4. Resolving Grouping, Type, and Identity Names

Grouping, type, and identity names are resolved in the context in which they are defined, rather than the context in which they are used. Users of groupings, typedefs, and identities are not required to import modules or include submodules to satisfy all references made by the original definition. This behaves like static scoping in a conventional programming language. For example, if a module defines a grouping in which a type is referenced, when the grouping is used in a second module, the type is resolved in the context of the original module, not the second module. There is no worry over conflicts if both modules define the type, since there is no ambiguity.

5.5. Nested Typedefs and Groupings

Typedefs and groupings may appear nested under many YANG statements, allowing these to be lexically scoped by the hierarchy under which they appear. This allows types and groupings to be defined near where they are used, rather than placing them at the top level of the hierarchy. The close proximity increases readability.
Top   ToC   RFC6020 - Page 30
   Scoping also allows types to be defined without concern for naming
   conflicts between types in different submodules.  Type names can be
   specified without adding leading strings designed to prevent name
   collisions within large modules.

   Finally, scoping allows the module author to keep types and groupings
   private to their module or submodule, preventing their reuse.  Since
   only top-level types and groupings (i.e., those appearing as
   substatements to a module or submodule statement) can be used outside
   the module or submodule, the developer has more control over what
   pieces of their module are presented to the outside world, supporting
   the need to hide internal information and maintaining a boundary
   between what is shared with the outside world and what is kept

   Scoped definitions MUST NOT shadow definitions at a higher scope.  A
   type or grouping cannot be defined if a higher level in the schema
   hierarchy has a definition with a matching identifier.

   A reference to an unprefixed type or grouping, or one which uses the
   prefix of the current module, is resolved by locating the closest
   matching "typedef" or "grouping" statement among the immediate
   substatements of each ancestor statement.

5.6. Conformance

Conformance is a measure of how accurately a device follows the model. Generally speaking, devices are responsible for implementing the model faithfully, allowing applications to treat devices which implement the model identically. Deviations from the model can reduce the utility of the model and increase fragility of applications that use it. YANG modelers have three mechanisms for conformance: o the basic behavior of the model o optional features that are part of the model o deviations from the model We will consider each of these in sequence.
Top   ToC   RFC6020 - Page 31

5.6.1. Basic Behavior

The model defines a contract between the NETCONF client and server, which allows both parties to have faith the other knows the syntax and semantics behind the modeled data. The strength of YANG lies in the strength of this contract.

5.6.2. Optional Features

In many models, the modeler will allow sections of the model to be conditional. The device controls whether these conditional portions of the model are supported or valid for that particular device. For example, a syslog data model may choose to include the ability to save logs locally, but the modeler will realize that this is only possible if the device has local storage. If there is no local storage, an application should not tell the device to save logs. YANG supports this conditional mechanism using a construct called "feature". Features give the modeler a mechanism for making portions of the module conditional in a manner that is controlled by the device. The model can express constructs that are not universally present in all devices. These features are included in the model definition, allowing a consistent view and allowing applications to learn which features are supported and tailor their behavior to the device. A module may declare any number of features, identified by simple strings, and may make portions of the module optional based on those features. If the device supports a feature, then the corresponding portions of the module are valid for that device. If the device doesn't support the feature, those parts of the module are not valid, and applications should behave accordingly. Features are defined using the "feature" statement. Definitions in the module that are conditional to the feature are noted by the "if-feature" statement with the name of the feature as its argument. Further details are available in Section 7.18.1.

5.6.3. Deviations

In an ideal world, all devices would be required to implement the model exactly as defined, and deviations from the model would not be allowed. But in the real world, devices are often not able or designed to implement the model as written. For YANG-based
Top   ToC   RFC6020 - Page 32
   automation to deal with these device deviations, a mechanism must
   exist for devices to inform applications of the specifics of such

   For example, a BGP module may allow any number of BGP peers, but a
   particular device may only support 16 BGP peers.  Any application
   configuring the 17th peer will receive an error.  While an error may
   suffice to let the application know it cannot add another peer, it
   would be far better if the application had prior knowledge of this
   limitation and could prevent the user from starting down the path
   that could not succeed.

   Device deviations are declared using the "deviation" statement, which
   takes as its argument a string that identifies a node in the schema
   tree.  The contents of the statement details the manner in which the
   device implementation deviates from the contract as defined in the

   Further details are available in Section 7.18.3.

5.6.4. Announcing Conformance Information in the <hello> Message

The namespace URI MUST be advertised as a capability in the NETCONF <hello> message to indicate support for the YANG module by a NETCONF server. The capability URI advertised MUST be of the form: capability-string = namespace-uri [ parameter-list ] parameter-list = "?" parameter *( "&" parameter ) parameter = revision-parameter / module-parameter / feature-parameter / deviation-parameter revision-parameter = "revision=" revision-date module-parameter = "module=" module-name feature-parameter = "features=" feature *( "," feature ) deviation-parameter = "deviations=" deviation *( "," deviation ) Where "revision-date" is the revision of the module (see Section 7.1.9) that the NETCONF server implements, "module-name" is the name of module as it appears in the "module" statement (see Section 7.1), "namespace-uri" is the namespace URI for the module as it appears in the "namespace" statement (see Section 7.1.3), "feature" is the name of an optional feature implemented by the device (see Section 7.18.1), and "deviation" is the name of a module defining device deviations (see Section 7.18.3). In the parameter list, each named parameter MUST occur at most once.
Top   ToC   RFC6020 - Page 33 Modules
Servers indicate the names of supported modules via the <hello> message. Module namespaces are encoded as the base URI in the capability string, and the module name is encoded as the "module" parameter to the base URI. A server MUST advertise all revisions of all modules it implements. For example, this <hello> message advertises one module "syslog". <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capability>;revision=2008-04-01 </capability> </hello> Features
Servers indicate the names of supported features via the <hello> message. In <hello> messages, the features are encoded in the "features" parameter within the URI. The value of this parameter is a comma-separated list of feature names that the device supports for the specific module. For example, this <hello> message advertises one module, informing the client that it supports the "local-storage" feature of module "syslog". <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capability>;features=local-storage </capability> </hello> Deviations
Device deviations are announced via the "deviations" parameter. The value of the "deviations" parameter is a comma-separated list of modules containing deviations from the capability's module. For example, this <hello> message advertises two modules, informing the client that it deviates from module "syslog" according to the deviations listed in the module "my-devs".
Top   ToC   RFC6020 - Page 34
   <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

5.7. Data Store Modification

Data models may allow the server to alter the configuration data store in ways not explicitly directed via NETCONF protocol messages. For example, a data model may define leafs that are assigned system- generated values when the client does not provide one. A formal mechanism for specifying the circumstances where these changes are allowed is out of scope for this specification.

(page 34 continued on part 3)

Next Section