14.3 YANG Data Modeling: Modules, Tree Structures, and Data Representation

YANG Data Modeling: Modules, Tree Structures, and Data Representation

Traditional network management relied heavily on Simple Network Management Protocol (SNMP) for monitoring and Command-Line Interface (CLI) screen-scraping for configuration. While SNMP effectively delivered basic operational counters through Management Information Bases (MIBs), it proved inadequate for device configuration due to complex Object Identifier (OID) structures, lack of transactional commit capabilities, and incomplete MIB coverage. Conversely, CLI configuration scripting lacked formal data typing, structure, and deterministic error handling. A minor operating system upgrade could alter command syntax or the formatting of operational output, breaking production scripts. To overcome these limitations, modern network automation decouples data modeling from network transport. YANG (Yet Another Next Generation), standardized in RFC 6020 (YANG 1.0) and updated in RFC 7950 (YANG 1.1), serves as the data modeling language that defines the structure, syntax, and operational rules for network devices.

+-------------------------------------------------------------------------+
|              Model-Driven Programmability Architecture                  |
+-------------------------------------------------------------------------+
|                         YANG Data Models                                |
|  Defines the Schema Contract: What data can exist, types, & constraints |
|  [Native: Cisco-IOS-XE]     [OpenConfig]     [IETF: RFC 8343 / 8349]    |
+-------------------------------------------------------------------------+
                                     |
        +----------------------------+----------------------------+
        |                                                         |
        v                                                         v
+--------------------------------+       +--------------------------------+
|      NETCONF (RFC 6241)        |       |      RESTCONF (RFC 8040)       |
|  Wire Encoding: XML            |       |  Wire Encoding: JSON / XML     |
|  Transport: SSH (Port 830)     |       |  Transport: HTTPS (Port 443)   |
|  Operations: <get-config>,     |       |  Operations: GET, POST, PUT,   |
|              <edit-config>     |       |              PATCH, DELETE     |
+--------------------------------+       +--------------------------------+
        |                                                         |
        +----------------------------+----------------------------+
                                     v
+-------------------------------------------------------------------------+
| Cisco IOS XE Network Element (Datastores: Running, Startup, Candidate)  |
+-------------------------------------------------------------------------+

YANG Architecture: Modules, Statements, and Reusability

YANG is not a data encoding or transport protocol. It is a schema definition language—analogous to a database schema or XML Schema Definition (XSD)—that dictates what data can be sent, received, and validated across programmable interfaces like NETCONF and RESTCONF.

Modules and Submodules

A YANG data model is written as a text module ending in the .yang extension. Large models can be broken into submodules to improve maintainability:

• module Statement: Declares the name of the YANG module.
• namespace: A globally unique Uniform Resource Identifier (URI) that disambiguates elements defined within the module, preventing naming collisions when multiple models are loaded on the same device.
• prefix: A short, unique shorthand prefix used within the module and by importing modules to reference its definitions.
• import and include: import pulls in definitions from external modules (such as importing standard IP address types from ietf-inet-types), while include incorporates submodules belonging to the same parent module.
• revision: Documents model evolution with a date stamp (YYYY-MM-DD) and description, maintaining backward compatibility.

Reusable Data Definitions: typedef and grouping

YANG promotes modular schema design through reusable constructs:

• typedef (Type Definition): Defines a new custom data type derived from built-in base types (such as uint32 or string), applying constraints such as ranges, lengths, or regular expression patterns. For example, a custom vlan-id type might restrict integer values strictly between 1 and 4094.
• grouping and uses: A grouping defines a reusable collection of data nodes (analogous to a class or structure). Other sections of the model instantiate the grouping using the uses statement, preventing code duplication across different interfaces or protocol blocks.

Core YANG Data Nodes

YANG models represent network state hierarchically through four primary data node statements:

Core YANG Data Node Types:
+-------------------------------------------------------------------------+
|  container interfaces {                  <-- Organizational container   |
|    list interface {                      <-- List of structured entries |
|      key "name";                         <-- Unique list key identifier |
|      leaf name { type string; }          <-- Single scalar value        |
|      leaf enabled { type boolean; }      <-- Single scalar value        |
|      leaf-list ip-address {              <-- Array of typed scalars     |
|        type inet:ipv4-address;           |                              |
|      }                                   |                              |
|    }                                     |                              |
|  }                                                                      |
+-------------------------------------------------------------------------+

1. container

A container is an organizational node used to group related child nodes together in the hierarchy. A container does not hold a value itself; its sole purpose is to structure and encapsulate child nodes (leaves, lists, or other containers). In an XML or JSON payload, a container appears as an enclosing element or nested object.

2. leaf

A leaf node contains exactly one scalar value and has no child nodes. Every leaf must declare an explicit type statement specifying its valid values. Built-in types include string, int32, uint16, boolean, enumeration, and empty. For example:

leaf mtu {
  type uint16 {
    range "64..9216";
  }
  default 1500;
  description "Maximum Transmission Unit in bytes";
}

3. leaf-list

A leaf-list defines an array of scalar values of a specific data type. Unlike a standard list, elements within a leaf-list do not have child nodes or unique key leaves; they are simply a sequence of individual values. A common use case is defining a list of NTP server addresses or DNS name servers:

leaf-list search-domain {
  type string;
  description "Ordered list of DNS domain search suffixes";
}

4. list

A list defines a sequence of structured entries, analogous to a database table or a list of dictionaries. Each list entry contains child nodes (such as leaves and containers) and must be uniquely identified by one or more key leaves. The key leaf uniquely distinguishes each entry in the list (e.g., interface names or BGP neighbor IP addresses):

list interface {
  key "name";
  leaf name {
    type string;
  }
  leaf description {
    type string;
  }
  leaf enabled {
    type boolean;
    default true;
  }
}

YANG Data Node Types Comparison Matrix

Configuration Data (config true) vs. Operational State (config false)

A fundamental architectural principle of YANG is the strict separation between configuration data and operational state data:

• Configuration Data (config true): Represents the administrative intent configured by an operator or management system. If not explicitly specified, nodes inherit config true by default. Configuration data resides in configuration datastores (such as running, startup, and candidate). It can be read, created, modified, and deleted via NETCONF <edit-config> or RESTCONF PUT/POST/PATCH operations.
• Operational State Data (config false): Represents real-time runtime state, physical operational status, hardware environmentals (temperature, fan speeds), and dynamic statistics (packet counters, CRC errors, BGP session uptime). Operational nodes are read-only. They cannot be modified by administrative configuration commands. Operational state is retrieved using NETCONF <get> (in contrast to <get-config>, which retrieves only configuration data) or RESTCONF GET operations.

YANG Model Categories: Native vs. OpenConfig vs. IETF

Enterprise network devices host multiple categories of YANG models simultaneously, each serving different operational requirements:

+-------------------------------------------------------------------------+
|                        YANG Model Classifications                       |
+-------------------------------------------------------------------------+
| 1. Native Models (Vendor-Specific)                                      |
|    Module Prefix: 'Cisco-IOS-XE-native'                                 |
|    Characteristics: broadest platform coverage, deep proprietary         |
|    knobs, Cisco-specific syntax; zero multi-vendor portability.         |
+-------------------------------------------------------------------------+
| 2. OpenConfig Models (Vendor-Neutral Consortium)                        |
|    Module Prefix: 'openconfig-interfaces', 'openconfig-bgp'             |
|    Characteristics: Operator-driven (Google, AT&T), uniform models      |
|    across Cisco, Arista, Juniper; limited to common denominator features|
+-------------------------------------------------------------------------+
| 3. IETF Models (Standardized RFCs)                                      |
|    Module Prefix: 'ietf-interfaces' (RFC 8343), 'ietf-routing'          |
|    Characteristics: Formal open standards, baseline interoperability,   |
|    slower standards cycle; minimal proprietary extension support.       |
+-------------------------------------------------------------------------+

1. Native Models (Vendor-Specific)

Authored directly by network equipment manufacturers (e.g., Cisco-IOS-XE-native.yang). Native models provide comprehensive coverage of platform-specific features, matching the full depth of the traditional CLI. However, native models are non-portable across vendors; a script written for Cisco IOS XE native models cannot configure a Juniper or Arista switch.

2. OpenConfig Models (Vendor-Neutral)

OpenConfig is an informal working group of network operators—including Google, Microsoft, AT&T, and Comcast—that develops vendor-neutral, open-source data models. Supported by major networking vendors, OpenConfig models (e.g., openconfig-interfaces.yang, openconfig-bgp.yang) enable organizations to write single automation workflows that manage multi-vendor infrastructure consistently. Because OpenConfig focuses on common operational capabilities, advanced proprietary hardware features may not be exposed.

3. IETF Models (Standard RFCs)

Standardized by the Internet Engineering Task Force (IETF) through standard RFCs, such as RFC 8343 (ietf-interfaces) and RFC 8349 (ietf-routing). IETF models provide baseline interoperability for foundational networking features. They are widely implemented but tend to have slower evolution cycles compared to OpenConfig.

YANG Model Categories Comparison Matrix

Visualizing YANG Models with pyang

YANG files can be thousands of lines long, making raw text files difficult to inspect. The open-source pyang Python utility validates YANG modules and visualizes their hierarchy as tree diagrams:

pyang -f tree ietf-interfaces.yang

Interpreting pyang Tree Notation

module: ietf-interfaces
  +--rw interfaces
  |  +--rw interface* [name]
  |     +--rw name                        string
  |     +--rw description?                string
  |     +--rw type                        identityref
  |     +--rw enabled?                    boolean
  |     +--ro oper-status                 enumeration
  |     +--ro last-change?                yang:date-and-time
  |     +--ro statistics
  |        +--ro in-octets?               yang:counter64
  |        +--ro in-unicast-pkts?         yang:counter64
  |        +--ro in-errors?               yang:counter64
  |        +--ro out-octets?              yang:counter64

• Hierarchy Lines (+--, |): Illustrate parent-child relationships and nesting depth.
• Access Permissions:
  • +--rw: Indicates read-write configuration data (config true). These nodes can be modified by configuration management tools.
  • +--ro: Indicates read-only operational state data (config false). These nodes represent live hardware counters and runtime status.
  • +---x: Indicates an executable Remote Procedure Call (RPC) operation.
  • +---n: Indicates a notification (RFC 8340 tree notation).
• Cardinality and Structural Symbols:
  • Node names followed by * indicate a list or leaf-list (0 to many entries).
  • Node names followed by ? indicate an optional node (0 or 1 instance).
  • Brackets [...] following a list name indicate the designated key leaf (e.g., [name]).
  • Right-hand labels specify the data type (e.g., string, boolean, identityref, yang:counter64).