YANG concepts

If the vocabulary around YANG is new to you, this page explains it through the things YANG Studio actually shows you. Every example below is real output from a Cisco IOS-XE device rather than an invented sample.

What comes back when you connect

When a NETCONF session opens, the client and the device each announce what they support. The device in this example sends back 522 capability strings: 15 that describe the protocol itself, and 507 that describe the YANG modules it implements. Here is one of those 507, exactly as it arrived:

urn:ietf:params:xml:ns:yang:ietf-interfaces?module=ietf-interfaces&revision=2014-05-08
  &features=pre-provisioning,if-mib,arbitrary-names
  &deviations=cisco-xe-ietf-ip-deviation

What you are downloading

When you press Download, YANG Studio sends one <get-schema> request for each module you picked, and the device replies with the module's source text. That text is the schema. It is meant to be read by people as well as parsers, and reading a little of it is the quickest way to get comfortable with YANG:

container interfaces {          // a fixed node — exists once
  list interface {             // repeats; one entry per interface
    key "name";                // what makes each entry unique

    leaf name {                // a single value...
      type string;             // ...of this type
    }
    leaf enabled {
      type boolean;
      default true;
    }
  }
}

Four keywords do most of the work in YANG. A container groups related nodes together and appears once. A list repeats, with one entry per interface or neighbour or route, and it needs a key to tell those entries apart. A leaf holds a single typed value, and that is where the actual data lives. Almost everything else in the language is a refinement of those four.

Why it asks for other modules too

Modules are not self-contained. They borrow type definitions from one another, and they declare that at the top of the file:

// in ietf-ip.yang
import ietf-inet-types { prefix inet; }

// and later
leaf address { type inet:ipv4-address-no-zone; }

So what is an ipv4-address-no-zone? Nothing in ietf-ip answers that question. The definition lives in the other file, where it turns out to be a string with a validation pattern attached. Without that second file, the parser genuinely cannot tell you what the leaf will accept, what to validate against, or what to suggest while you type.

That is what the message "will not parse yet — 4 imports missing" is telling you. It is not the app being fussy. The tree cannot be built at all until those files are present.

Why a repository and a set

This is the distinction that catches most people out, and it is worth being precise about, because the two answer genuinely different questions.

You might reasonably ask why the app cannot just parse the whole repository and skip the extra step. These two measurements are the answer:

Those BFD modules all add nodes to the same place in the routing tree, so loading them together produces a genuine conflict. On top of that, 23 of the module names in the IETF collection exist at two different revisions, and a single tree can only use one of them. Between the two problems, there is no such thing as "the tree for this repository". Choosing a set is what makes a tree possible at all.

What a set gets you

Once a set is parsed, every node in it carries two pieces of information that you will use constantly. The first is a path that addresses it:

/if:interfaces/if:interface/if:description

The second is whether you are allowed to write to it. YANG marks operational data with config false, and YANG Studio turns that into a badge on every node:

Attempting to write to a state node is one of the most common mistakes when you are starting out. The badge tells you before you try, rather than the device rejecting the request afterwards.

Features narrow the tree

Parts of a YANG module can be marked optional, and a device declares which of those it has turned on. The device in these examples implements pre-provisioning, if-mib and arbitrary-names, and nothing else. Because YANG Studio knows that, a set built from the device's own capabilities leaves out the nodes it does not support — here that removed if-index and link-up-down-trap-enable.

The difference is small in this example, but on a full vendor model it is the difference between a schema for the product family and a schema for the box actually in front of you.

The vocabulary

These are the terms you will run into while browsing a tree. As above, the first four account for the large majority of what you will see.