YANG Data Models

YANG data modeling language, pyang validation tools, and model-driven telemetry on Cisco platforms.

YANG Fundamentals

YANG (Yet Another Next Generation) is a data modeling language for NETCONF and RESTCONF. It defines the structure of configuration and operational data — what you can read, write, and subscribe to on a network device.

Core YANG node types

Node Type     Description                              Example
─────────────────────────────────────────────────────────────────────
module        Top-level container for the model         ietf-interfaces
container     Grouping node (no data itself)            interface
leaf          Single value                              name, mtu, enabled
leaf-list     Ordered list of scalar values             dns-server addresses
list          Keyed collection of entries               interface entries keyed by name
choice        Mutually exclusive branches               address type (ipv4 or ipv6)
grouping      Reusable structure (like a template)      common-attributes
uses          Instantiates a grouping                   uses common-attributes
augment       Extends another model's structure         adds vendor-specific leafs

Minimal YANG module structure

module example-system {
  namespace "urn:example:system";
  prefix sys;

  import ietf-inet-types {
    prefix inet;
  }

  container system {
    leaf hostname {
      type string;
      description "The device hostname";
    }
    leaf-list dns-server {
      type inet:ipv4-address;
      ordered-by user;
      description "DNS server addresses";
    }
    list ntp-server {
      key "address";
      leaf address {
        type inet:ipv4-address;
      }
      leaf enabled {
        type boolean;
        default true;
      }
    }
  }
}

Three Model Families

Model Family      Namespace Prefix        Maintained By         Scope
──────────────────────────────────────────────────────────────────────────
IETF              ietf-*                  IETF (RFC standards)  Vendor-neutral
OpenConfig        openconfig-*            OpenConfig WG         Multi-vendor operational
Cisco Native      Cisco-IOS-XE-*          Cisco                 Platform-specific full coverage
                  Cisco-IOS-XR-*
                  cisco-nx-os-*

When to use which model

Use Case                              Recommended Model
───────────────────────────────────────────────────────────────
Multi-vendor interface config         openconfig-interfaces
Multi-vendor BGP config               openconfig-bgp
IOS-XE specific (EIGRP, DMVPN)       Cisco-IOS-XE-native
NX-OS specific (vPC, FEX)            cisco-nx-os-device
Standards-based ACLs                  ietf-access-control-list

Cisco native models cover everything the CLI can do. IETF and OpenConfig cover a subset but work across vendors. Start with OpenConfig for multi-vendor; fall back to native for platform-specific features.

pyang — Model Exploration Tool

Install pyang

pip install pyang

Clone Cisco YANG models from GitHub

git clone https://github.com/YangModels/yang.git ~/yang-models
ls ~/yang-models/vendor/cisco/xe/     # IOS-XE models by version
ls ~/yang-models/vendor/cisco/xr/     # IOS-XR models
ls ~/yang-models/vendor/cisco/nx/     # NX-OS models
ls ~/yang-models/standard/ietf/       # IETF standard models
ls ~/yang-models/experimental/openconfig/  # OpenConfig models

Generate tree view — the most useful pyang output format

pyang -f tree ietf-interfaces.yang

Output

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

Tree notation:

Symbol   Meaning
──────────────────────────
+--rw    Read-write (config data)
+--ro    Read-only (operational/state data)
+--x     RPC or action
+--n     Notification
*        List (multiple instances, keyed)
?        Optional leaf

Generate tree for a specific subtree — drill into one container

pyang -f tree --tree-path /native/interface ietf-interfaces.yang

Generate tree with depth limit — top-level overview only

pyang -f tree --tree-depth 3 Cisco-IOS-XE-native.yang

Validate a YANG model for errors

pyang --lint ietf-interfaces.yang

Convert YANG to other formats

# To UML diagram
pyang -f uml ietf-interfaces.yang -o interfaces.uml

# To DSDL (XML schema)
pyang -f dsdl ietf-interfaces.yang

# To JSON skeleton (sample instance data)
pyang -f sample-xml-skeleton ietf-interfaces.yang

Finding Models on a Device

List YANG models supported by a device via NETCONF capabilities

ssh admin@10.50.1.10 -p 830 -s netconf <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities/>
</hello>
]]>]]>
EOF

The hello response lists every YANG module the device supports as capability URIs.

Extract model names from NETCONF hello — parse capabilities

ssh admin@10.50.1.10 -p 830 -s netconf <<'EOF' 2>/dev/null | grep -oP 'module=\K[^&]+' | sort -u
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities/>
</hello>
]]>]]>
EOF

Output (partial)

Cisco-IOS-XE-acl-oper
Cisco-IOS-XE-bgp-oper
Cisco-IOS-XE-interfaces-oper
Cisco-IOS-XE-native
ietf-interfaces
ietf-ip
openconfig-interfaces
openconfig-bgp

Deviations & Augmentations

Deviation — a vendor declares what parts of a standard model it does NOT support

module cisco-xe-ietf-interfaces-deviation {
  namespace "urn:cisco:params:xml:ns:yang:cisco-xe-ietf-interfaces-deviation";

  deviation "/if:interfaces/if:interface/if:type" {
    deviate replace {
      type string;  // Replace identityref with plain string
    }
  }

  deviation "/if:interfaces/if:interface/if:statistics/if:discontinuity-time" {
    deviate not-supported;  // This leaf is not implemented
  }
}

Augmentation — a vendor adds leaves to a standard model

module cisco-xe-ietf-interfaces-augment {
  namespace "urn:cisco:params:xml:ns:yang:cisco-xe-ietf-interfaces-augment";

  augment "/if:interfaces/if:interface" {
    leaf negotiation-auto {
      type boolean;
      description "Enable auto-negotiation on the interface";
    }
    leaf channel-group {
      type uint16;
      description "EtherChannel group number";
    }
  }
}

Find deviation models for a platform

find ~/yang-models/vendor/cisco/xe/17121/ -name "*deviation*" | head -10

Output

cisco-xe-ietf-interfaces-deviation.yang
cisco-xe-ietf-ip-deviation.yang
cisco-xe-openconfig-bgp-deviation.yang
cisco-xe-openconfig-interfaces-deviation.yang

Always check deviation models before using IETF or OpenConfig models against Cisco devices. The standard model may define features that the device explicitly does not implement. Deviations are per-platform and per-version.

Practical Workflow

End-to-end workflow: find a model, explore it, use it

# 1. Find what models the device supports
ssh admin@switch -p 830 -s netconf <<'EOF' 2>/dev/null | grep -oP 'module=\K[^&]+' | grep -i interface
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><capabilities/></hello>
]]>]]>
EOF

# 2. Explore the model tree
pyang -f tree --tree-depth 4 ~/yang-models/vendor/cisco/xe/17121/Cisco-IOS-XE-native.yang \
  --path ~/yang-models/vendor/cisco/xe/17121/ \
  --tree-path /native/interface

# 3. Check for deviations
pyang -f tree ~/yang-models/vendor/cisco/xe/17121/cisco-xe-openconfig-interfaces-deviation.yang \
  --path ~/yang-models/vendor/cisco/xe/17121/

# 4. Use the model via RESTCONF (see restconf-quick-reference)
# or NETCONF (see netconf-quick-reference)