YANG Language Deep Dive

Objective

In this lesson you will learn to read and interpret YANG models — focusing on the syntax elements container, list, leaf, augment, and deviation. You will learn the theory (what each statement means and how the data is represented) and practical techniques for mapping YANG to operational data exposed via programmatic interfaces such as RESTCONF and NETCONF/gNMI. This matters in production because YANG is the contract between your network device and automation tools: if you can read a YANG model you can reliably request, validate, and change device intent at scale (for example, when onboarding thousands of devices with consistent configuration).

Real-world scenario: an operations team is building an intent-based workflow to configure interface attributes and telemetry subscriptions across hundreds of IOS XE devices. Correctly interpreting the vendor YANG models is required to know exactly which leaf names and containers the management tooling must populate.

---

Topology & Device Table

ASCII topology (management-plane only). IP addresses use reserved TEST-NET-1 addresses suitable for lab use.

R1 is an IOS XE device exposing RESTCONF/NETCONF. YANG-SRV is a Linux host running YANG Suite / file storage and acting as the operator workstation.

Device table

Device	Interface	IP Address	Subnet Mask	Role
R1	GigabitEthernet0/0	192.0.2.1	255.255.255.0	IOS XE device (RESTCONF/NETCONF/gNMI)
YANG-SRV	eth0	192.0.2.10	255.255.255.0	Operator workstation (YANG Suite, curl)

Tip: In production, the management plane is often kept on a separate VLAN/subnet and protected by TACACS/AAA and certificate-based TLS. For this lesson we use simple IP addressing to focus on YANG syntax.

---

Key Concepts (theory before hands-on)

• YANG as a data modeling language: YANG defines the structure of configuration and operational data. Think of a YANG module as a schema (like JSON Schema or SQL table definitions) that tells you the names, types, hierarchy, constraints, and defaults for device-managed data. In production, automation tools use YANG to generate correct payloads and avoid invalid configuration.

• container, list, leaf:

  • container groups related nodes (like an object). It does not imply multiplicity.
  • list represents repeated entries (like a table). Each entry can have a key; lists are the YANG analogue of arrays.
  • leaf is a single data value (string, uint16, boolean, enumeration). Leaves are the fields operators set.
  • Packet/operation behavior: when using NETCONF/RESTCONF, get-config/get requests return these nodes in XML/JSON following the YANG structure.

• augment and deviation:

  • augment lets one module add nodes to another module's model at defined locations — used by vendors to extend base models without modifying them.
  • deviation allows a device vendor to declare differences from a standard model (for example, unsupported features or different type constraints).
  • In production, automation must detect augmentations and deviations so it manipulates the correct nodes for a particular platform.

• Encoding, transport, and security (practical implications):

  • NETCONF default port 830 uses XML over SSH; RESTCONF uses HTTPS (port 443), encoding XML or JSON; gNMI uses HTTP/2 and protobuf/JSON.
  • When scripting, choose the transport required by your toolkit and platform. For example, a JSON payload for RESTCONF must follow the YANG names and hierarchy (RFC7951).

---

Step-by-step configuration and analysis

Step 1: Configure management interface on R1

What we are doing: Assign a management IP on R1 so the operator workstation can reach RESTCONF/NETCONF endpoints. This is necessary to fetch YANG modules and interact programmatically.

configure terminal
interface GigabitEthernet0/0
 description Management interface for RESTCONF/NETCONF
 ip address 192.0.2.1 255.255.255.0
 no shutdown
exit
end
write memory

What just happened:

• The interface GigabitEthernet0/0 received the IP 192.0.2.1/24 and was administratively brought up.
• Writing the configuration persists the change. In a real device, this management IP is what RESTCONF or NETCONF clients will use to open a TLS or SSH session to request data modeled by YANG.

Real-world note: In production you would use AAA and certificates instead of plain local accounts, and place the management interface on a protected management VLAN.

Verify:

show running-config interface GigabitEthernet0/0
interface GigabitEthernet0/0
 description Management interface for RESTCONF/NETCONF
 ip address 192.0.2.1 255.255.255.0
 no shutdown

---

Step 2: Inspect a simple YANG module file on the operator workstation

What we are doing: Open a representative YANG module that demonstrates container/list/leaf/augment/deviation. Reading modules is the primary skill — you must map model nodes to intended configuration.

cat /home/nhprep/models/example-interfaces.yang
module example-interfaces {
  namespace "urn:nhprep:example:interfaces";
  prefix ex-if;

  container interfaces {
    list interface {
      key "name";
      leaf name {
        type string;
      }
      leaf enabled {
        type boolean;
        default true;
      }
      leaf mtu {
        type uint16;
        default 1500;
      }
    }
  }
}

module ex-augment {
  namespace "urn:nhprep:augment";
  prefix aug;

  augment "/example-interfaces:interfaces/interface" {
    leaf alias {
      type string;
    }
  }
}

module ex-deviation {
  namespace "urn:nhprep:deviation";
  prefix dev;

  deviation /example-interfaces:interfaces/interface/mtu {
    dev-replace;
    type uint32;
  }
}

What just happened:

• The YANG file shows a top-level container named interfaces. Inside is a list called interface keyed by name. The list entries include leaves: name, enabled, mtu.
• ex-augment shows an augment that adds an alias leaf to each interface list entry — augment extends another module.
• ex-deviation shows a deviation on the mtu leaf, replacing the type from uint16 to uint32 (this represents a vendor-specific change to the base model).

Real-world note: Vendors often augment standard models (e.g., OpenConfig) with device-specific attributes; automation must discover these via /restconf/data/schema or capability calls.

Verify:

more /home/nhprep/models/example-interfaces.yang
module example-interfaces {
  namespace "urn:nhprep:example:interfaces";
  prefix ex-if;

  container interfaces {
    list interface {
      key "name";
      leaf name {
        type string;
      }
      leaf enabled {
        type boolean;
        default true;
      }
      leaf mtu {
        type uint16;
        default 1500;
      }
    }
  }
}

module ex-augment {
  namespace "urn:nhprep:augment";
  prefix aug;

  augment "/example-interfaces:interfaces/interface" {
    leaf alias {
      type string;
    }
  }
}

module ex-deviation {
  namespace "urn:nhprep:deviation";
  prefix dev;

  deviation /example-interfaces:interfaces/interface/mtu {
    dev-replace;
    type uint32;
  }
}

---

Step 3: Map YANG nodes to RESTCONF GET paths

What we are doing: Demonstrate how a YANG container/list/leaf maps to RESTCONF resource paths and JSON payloads. This is essential because automation uses these paths.

# Example RESTCONF GET for all interfaces (HTTPS to port 443, using basic auth in this lab)
curl -k -u admin:Lab@123 https://192.0.2.1/restconf/data/example-interfaces:interfaces

What just happened:

• RESTCONF paths mirror YANG module structure. The container interfaces is accessed at /restconf/data/<module-prefix>:interfaces.
• A GET returns the content of that container in XML or JSON (RFC7951 for JSON). In production, replace basic auth with certificates and use HTTPS with validation.

Real-world note: Tools like YANG Suite or Postman can discover modules and show the correct names/prefixes and namespaces for forming RESTCONF requests.

Verify (expected output):

{
  "example-interfaces:interfaces": {
    "interface": [
      {
        "name": "GigabitEthernet0/0",
        "enabled": true,
        "mtu": 1500,
        "alias": "Mgmt0"    // present because augment adds alias
      },
      {
        "name": "GigabitEthernet0/1",
        "enabled": false,
        "mtu": 9000
      }
    ]
  }
}

---

Step 4: Reading list keys, defaults, and constraints in a model

What we are doing: Explain how keys and defaults operate and how they affect payloads sent by automation. This step prevents common errors like omitting keys.

# Conceptual: creating or editing an interface list entry via RESTCONF (JSON)
curl -k -u admin:Lab@123 -X POST -H "Content-Type: application/yang-data+json" \
 https://192.0.2.1/restconf/data/example-interfaces:interfaces \
 -d '{"interface":[{"name":"GigabitEthernet0/2","enabled":true,"mtu":1500,"alias":"Uplink2"}]}'

What just happened:

• The name leaf is the key for the list; it uniquely identifies the entry. When creating an entry, the key must be present in the payload.
• Defaults like enabled true mean if the field is missing the device will assume the declared default. However explicit values are recommended for clarity in automated workflows.

Real-world note: Some tooling requires keys in the URL rather than the payload (e.g., POST vs PUT semantics). Always check module documentation.

Verify (expected response from POST and subsequent GET):

# POST response: HTTP/1.1 201 Created
HTTP/1.1 201 Created
Content-Length: 0

# GET to confirm:
curl -k -u admin:Lab@123 https://192.0.2.1/restconf/data/example-interfaces:interfaces/interface=GigabitEthernet0/2
{
  "example-interfaces:interface": {
    "name": "GigabitEthernet0/2",
    "enabled": true,
    "mtu": 1500,
    "alias": "Uplink2"
  }
}

---

Step 5: Interpreting augment and deviation impacts

What we are doing: Show how augment and deviation change the effective schema and why a client must account for them.

# Fetch YANG schema metadata (conceptual RESTCONF call to the schema or modules endpoint)
curl -k -u admin:Lab@123 https://192.0.2.1/restconf/data/ietf-yang-library:modules-state

What just happened:

• The device exposes the modules it implements. A client inspecting modules-state discovers that ex-augment and ex-deviation are present, meaning the base example-interfaces model has been extended and altered.
• An augment adds the alias leaf into the interface entries; a deviation replaces mtu type to uint32 so tooling cannot assume uint16 (important for value ranges).

Real-world note: When pushing configs at scale, failing to process deviations can cause type mismatch errors or rejected payloads. Always inspect device-capabilities or yang-library.

Verify (expected excerpt from modules-state):

{
  "ietf-yang-library:modules-state": {
    "module": [
      {
        "name": "example-interfaces",
        "revision": "2025-01-01",
        "namespace": "urn:nhprep:example:interfaces"
      },
      {
        "name": "ex-augment",
        "revision": "2025-01-01",
        "namespace": "urn:nhprep:augment"
      },
      {
        "name": "ex-deviation",
        "revision": "2025-01-01",
        "namespace": "urn:nhprep:deviation"
      }
    ]
  }
}

---

Verification Checklist

• Check 1: R1 management interface is reachable — verify with ping from YANG-SRV and with show running-config interface GigabitEthernet0/0.
  • Verification command: show running-config interface GigabitEthernet0/0 (expected config shown in Step 1 verification).
• Check 2: Example YANG module is present on the operator workstation — verify with cat /home/nhprep/models/example-interfaces.yang.
  • Verification command: more /home/nhprep/models/example-interfaces.yang (expected content shown in Step 2).
• Check 3: RESTCONF GET returns the interface list with augment alias and respects the deviation on mtu.
  • Verification command: curl -k -u admin:Lab@123 https://192.0.2.1/restconf/data/example-interfaces:interfaces (expected JSON shown in Step 3).

---

Common Mistakes

Symptom	Cause	Fix
RESTCONF GET returns no alias leaf	Client is querying base module only; device augment not discovered	Query ietf-yang-library:modules-state to confirm installed modules and include augment module prefix in path or expect augmented nodes under base path
Payload rejected with type error on mtu	Client assumed uint16, but device reports deviation to uint32	Inspect device modules-state and update client schemas to accept uint32 for mtu
Creating a list entry fails with "missing key"	The list key (e.g., name) was omitted from payload	Include the key leaf in the JSON payload or in the URL as required by the API
Automation tool generates XML when device expects JSON	Encoding mismatch; RESTCONF supports XML or JSON (RFC7951)	Configure tool to use JSON or XML according to device supported encodings; confirm via yang-library or device docs

---

Key Takeaways

• YANG models define the exact schema (containers, lists, leaves) automation must use; reading YANG is as important as reading a CLI reference.
• A container groups related data, a list models repeating entries keyed by specific leaves, and a leaf is a single typed value; augment extends other modules and deviation records platform-specific differences.
• Always discover installed modules (modules-state / yang-library) and account for augmentations and deviations before constructing payloads — otherwise automation will encounter runtime errors.
• In production networks, this knowledge enables building robust, portable automation that works across IOS XE releases and vendor-specific extensions.

Warning: This lesson used basic authentication and unvalidated TLS for clarity. In production, always use PKI-based certificates and hardened management plane controls.

---

End of Lesson 1: YANG Language Deep Dive.