YANG data models

A YANG data model describes everything that can be configured on a device, everything that can be monitored, the actions it can take and the notifications it can send. It models data as a tree: a container holds other nodes, a list holds one entry per key, and a leaf holds a value of a type. config false marks state data a client cannot set.

In Daveth Pro (Network)10 min video

By , founder of Daveth · Updated

Opening frame of the video walkthrough of YANG data models

Watch this lesson

10 min · Video walkthrough

In Daveth Pro (Network)

The full 10 min walkthrough is in Daveth Pro (Network). See what the plan opens

What this page answers

What is a YANG data model?

A description of a device's configuration data, state data, remote procedure calls and notifications, written as a tree of nodes grouped into modules: the contract NETCONF and RESTCONF carry data against. Read it in “4.1 Why model the data at all”

What are containers, lists and leaves in YANG?

A container holds other nodes; a list holds one entry per key, and no two entries may share a key; a leaf holds a single value of a given type. A leaf marked config false is state data, not configuration. Read it in “4.1 Why model the data at all”

4.1 Why model the data at all

A script sends a device an interface entry with speed set to 1g. Another sends one with observed-speed set to 1000. Which one gets refused? Keep it for section 4.3.

The guide starts from what networks had before. SNMP is widely used for fault handling and monitoring but "not often used for configuration changes", and CLI scripting is used more. A script that types CLI commands and reads text back works like a person reading someone's handwriting over their shoulder: fine until they change their handwriting. YANG data models are the guide's alternative to SNMP's MIBs.

A data model describes everything that can be configured on a device, everything that can be monitored, the administrative actions it can take (resetting counters, rebooting) and the notifications it can send. RFC 7950 names the same four: configuration data, state data, remote procedure calls and notifications. Think of it as a form with its rules printed on the back: which boxes exist, what may go in each, and which boxes the office fills in, not you. Every vendor can describe its data in the same language, which is what the guide means by "a uniform way to describe data" across platforms. The models themselves aren't automatically shared: vendors publish native models of their own, like the Cisco native model behind the guide's Example 28-9, and data only looks the same across vendors where both implement the same standard model. Think of it as two countries sharing an alphabet: every letter is the same, but that doesn't mean they write the same words.

The benefit the guide doesn't spell out is the one you'll use most: because the rules are written down in a form a program can read, data can be checked against them before it's sent, and a mistake is caught by the tool instead of by the device at 2 a.m.

SNMP could always change configuration in principle, which is how "read-only community string" became the most frequently configured security feature in networking.

YANG models the data "as a tree in which each node has a name, and either a value or a set of child nodes", and it groups models into modules. Here is the guide's Example 28-6, the interface list from RFC 6020:

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;
  }
}

The pieces work like a filing cabinet. A container is a drawer that holds other nodes. A list is a drawer of folders, one per entry, and its key is the label on each folder: every entry must have one, and no two may share it. A leaf is a single field with a type: here a string, an enumeration of three values, and a 32-bit unsigned number. (A leaf-list holds several values of one type, such as a list of DNS domains.)

The syntax is braces and semicolons, which RFC 7950 calls "C-like", not XML; it's the data a model describes that travels as XML or JSON. And a model only compiles as part of a whole module, with a name, namespace and prefix; pyang refuses the guide's Example 28-6, as printed, with "expected one of ['module', 'submodule']". Tools print a model as a tree, and reading that notation is the fastest way into any model, like the contents page of a book you haven't read yet. Here is the guide's list, wrapped by the course in a module named course-demo:

module: course-demo
  +--rw interface* [name]
     +--rw name              string
     +--rw speed?            enumeration
     +--ro observed-speed?   uint32
MarkMeans
rwconfiguration: a client may write it
rostate: data the device reports, if it supports it
?optional
*a list (or leaf-list)
[name]the list's key

So each interface has exactly one name, an optional speed from three values, and an optional observed speed the device reports. The guide's reading says "a specific interface"; the rule applies to every entry, and each holds one speed, chosen from three.

The guide prints its YANG as bare statements, and pyang's first question is which module you meant, which is fair: even a filing cabinet needs to know whose office it's in.

"YANG models make a clear distinction between configuration data and state information". The switch is one statement: config false marks a node as state, reported by the device and never written by a client. In RFC 6020's words, the observed speed "cannot be manipulated using <edit-config>" (<edit-config> is NETCONF's write operation, 09-6). It's like a car's cruise control and its speedometer: you set the one, and the other only tells you what's actually happening.

That answers section 4.1: both scripts get refused. 1g isn't one of the enumeration's three values, and observed-speed is state, so it has no place in data a client writes. The same entry with observed-speed 1000 is fine as operational data, the configuration and state the device reports together. Types do the rest: a uint32 runs from 0 to 4294967295, so -1 and 4294967296 are both refused. In RFC 7951 JSON an enumeration is written as a string, so 100 as a JSON number fails before its value is even looked at; XML has only text, so there it would fail on its value instead. And the values are exact: AUTO fails where auto passes.

Predict before D1: add a second entry with the same name as the first. Both entries are well-formed on their own. Does the model accept the pair?

D1

YANG validation of an interface entry against its model: every leaf known, every value of the right type, each key unique.
Valid against this model: every leaf is in it, every value fits its type, and each entry has a unique key. That says nothing yet about whether a device will accept it.

No. The name is the list's key, and with two entries sharing it the list can't tell them apart. Take observed-speed at 1000, written by a client and then reported by the device: the verdict flips from invalid to valid, and nothing in the data changed, because whether a node may appear depends on who's sending it. Leave out the key and the entry has no identity; add a duplex leaf and the model has no such node; drop the module prefix and the validator doesn't know whose interface you mean. A validator is like a proofreader who knows the house style by heart: it can't tell you whether your sentence is wise, only whether it follows the rules.

Observed-speed is the one leaf in the model you can't configure, which makes it the only honest thing on the interface.

The guide's Example 28-5 comes from RFC 6020's section on choices, with one change: where the RFC's sports arena offers pretzels and beer, the guide's offers pretzels and popcorn.

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

A choice is a set of alternatives, "only one of which may be present in any one data tree", and each alternative is a case. It works like a set menu: pick from one combo, one item or all of them, but never mix combos. The validator agrees:

DataVerdict
pretzel and popcornvalid: both are in one case
pretzel and chocolateinvalid: two cases at once
chocolate first-availablevalid
chocolate whiteinvalid: not in the enumeration
no snack at allvalid: nothing makes the choice mandatory

Two more details. A leaf of type empty carries no value; it's either there or not, like a tick box, and RFC 7951 writes it in JSON as [null], so "pretzel": true is refused. And the guide's reading, "A choice must be made to have milk chocolate or dark chocolate", mixes up two statements: the choice is between the cases; milk, dark and first-available are the three values of one enumeration leaf.

One thing a single piece of data can't show: on a device, choosing the other case later isn't refused. "The creation of a node from one case implicitly deletes all nodes from all other cases". Only data holding both cases at once is refused.

The guide swapped RFC 6020's beer for popcorn, which is the most responsible edit in the chapter and leaves the structure exactly as it was.

A YANG model doesn't pick a wire format. The same interface entry can travel as XML or as JSON, and the model decides what's valid in both. It's like sheet music and its recordings: one score, on vinyl or streamed, and the notes are the same. In RFC 7951's JSON, a top-level name carries its module, "course-demo:interface"; the XML says the same with a namespace. That prefix is also how you can tell modelled JSON from ordinary API JSON: Figure 28-14's vManage reply has keys like "deviceId" and "host-name", with no module anywhere.

Table 28-6 puts YANG beside what SNMP used: SNMP's models are MIBs written in SMI and its resources are OIDs; NETCONF uses YANG models, and resources are paths, like interfaces/interface/eth0. Figure 28-15 draws the models on both sides, the devices and the management applications, and that's the point: both ends work from the same contract. Moving the data is NETCONF's and RESTCONF's job, not YANG's: 09-6 takes that up.

A model is a promise about data, not about a device. A device may implement only part of a module, and YANG even has a statement for saying so, deviation, for the parts "the server does not implement faithfully". So a validator's "valid" works like a plan checker approving drawings against the building code: the drawings comply, and whether the builder follows them is a separate inspection.