skip to content

In YANG, how does a vendor module use augment to add a QoS leaf to the standard ietf-interfaces list without editing that module?

level: middleimportance: must knowfreq 16%

answer

  1. graft, don't edit
  2. import plus absolute target path
  3. whose namespace owns the new leaf
  4. module-name:leaf in RFC 7951 JSON

basics

~10 s

The vendor module imports ietf-interfaces and declares augment "/if:interfaces/if:interface" with the new leaf inside. The leaf appears in every interface entry but belongs to the vendor module's namespace, so the standard module stays untouched.

solid answer

~40 s

The vendor module `import`s `ietf-interfaces` with a prefix and writes a top-level `augment "/if:interfaces/if:interface"`, whose argument is an absolute schema node identifier naming the target. RFC 7950 §7.17 lets the target be a container, list, choice, case, input, output or notification, never a leaf. The added nodes appear under every instance of the target, but they are defined in the **augmenting module's namespace**: in XML they carry the vendor's namespace URI, and in RFC 7951 JSON they are written `example-vendor-qos:qos-profile`, because their namespace differs from the parent's. So two vendors can add a same-named leaf without colliding, the standard module's revision never changes, and a client written only against `ietf-interfaces` keeps working as long as the augment adds nothing that client is forced to supply.

code

yang · 17 lines
yang
module example-vendor-qos {
  yang-version 1.1;
  namespace "urn:example:vendor-qos";
  prefix vqos;

  import ietf-interfaces {
    prefix if;
  }

  augment "/if:interfaces/if:interface" {
    leaf qos-profile {
      type string;
      description
        "Vendor QoS profile applied to this interface.";
    }
  }
}

go deeper

for a junior

Remember the one-line idea: augment adds nodes to a tree another module defines, without editing that module, and the new nodes belong to the module that wrote the augment.

for a middle

Explain the mechanics: import with a prefix, the absolute target path, the legal target kinds, and how the augmenting namespace shows up in XML, in RFC 7951 JSON member names and in RESTCONF paths.

for a senior

Show what it means in operation: same-named vendor leaves coexist, standard clients keep working only while the augment demands nothing new of them, and a reply now carries foreign-namespace nodes a strict client must tolerate.

for a principal

Weigh augmenting a standard model against shipping a parallel vendor-native tree: one schema for clients and standard-first tooling, against a dependency on the standard module's structure that you do not control.

## What problem augment solves Standard YANG modules such as `ietf-interfaces` (RFC 8343) are published once and then revised only by their owners. A vendor whose device has a proprietary **QoS profile** still wants the operator to set it *on the interface it applies to*, in the same tree a client already walks. Editing the standard module is not an option: every implementation would then ship a different "ietf-interfaces" and no client could trust the name. The **`augment`** statement (RFC 7950 §7.17) solves this. One module adds schema nodes into a tree that another module defines, without touching that module's text, its namespace or its revision. ## Anatomy of an augment 1. **Import the target module** with a prefix: `import ietf-interfaces { prefix if; }`. 2. **Name the target node** with a schema node identifier. At the top level of a module the absolute form is required, `augment "/if:interfaces/if:interface"`; inside a `uses` statement the descendant form is used instead, to extend a grouping's nodes at that spot. 3. **List the new nodes** in the body: leaves, containers, lists, leaf-lists, choices, `uses`, and in YANG 1.1 also `action` and `notification` when the target is a container or list. 4. Optionally add a **`when`** condition so the new nodes exist only in some entries, for example only on one interface type. After this, every `interface` entry may hold a `qos-profile` leaf. The list's key, its other leaves and the module's revision are unchanged. Because the augment lives in the vendor module, it ships, versions and is withdrawn with that module: a server that does not implement the vendor module simply has no `qos-profile` anywhere in its tree. ## Which targets are legal | Target node kind | What the augment may add | |---|---| | container or list | data definitions (`container`, `leaf`, `list`, `leaf-list`, `choice`, `uses`), plus `action` and `notification` | | case, input, output or notification | data definitions (`container`, `leaf`, `list`, `leaf-list`, `choice`, `uses`) | | choice | a `case`, or a shorthand case | | leaf or leaf-list | nothing: these are not legal targets | Because `input` and `output` are legal targets, a vendor can also add a parameter to a standard rpc by augmenting that rpc's `input` node. One more rule from §7.17: an augment MUST NOT add two nodes with the same name from the same module to one target. ## Whose namespace the new nodes live in The decisive rule (§7.17.2) is that **all data nodes defined in an augment belong to the namespace of the module that contains the augment**, not to the target's. Every encoding shows it: - **XML, as NETCONF carries it**: the new element is `<qos-profile xmlns="urn:example:vendor-qos">`, inside an `<interface>` element in the `urn:ietf:params:xml:ns:yang:ietf-interfaces` namespace. - **JSON (RFC 7951)**: a member name is namespace-qualified whenever its namespace differs from its parent's, so the leaf is written `"example-vendor-qos:qos-profile"`, with the module *name*, never its prefix. - **RESTCONF URIs (RFC 8040 §3.5.3)**: the same rule prepends `example-vendor-qos:` to the path segment where the module changes. - **Tree diagrams (RFC 8340)**: the additions are printed under their own heading, `augment /if:interfaces/if:interface:`, in the vendor module's diagram. A JSON instance of one augmented entry: ```json { "ietf-interfaces:interfaces": { "interface": [ { "name": "eth0", "type": "iana-if-type:ethernetCsmacd", "example-vendor-qos:qos-profile": "gold" } ] } } ``` What follows for the people running it: - Two vendors can each add a leaf called `qos-profile`; their namespaces keep the two apart. - The standard module is untouched, so what a client knows about `ietf-interfaces` stays true. - A client written only against `ietf-interfaces` keeps working, provided the augment never forces it to supply something new. That is why mandatory nodes inside an augment are restricted, a separate question. ## What augment is not - It is not **`uses`**. A `uses` copies a grouping's nodes into the place where the `uses` sits, in the using module's own tree; an augment grafts nodes into a tree somebody else defined. - It is not a **deviation**. A deviation records that a server departs from a module (drops or alters a node); an augment only adds. - It cannot add an **`rpc`**. An `rpc` is a top-level module statement, so it is never the child of a data node; to hang an operation on the interface list, an augment adds an `action` instead.

  • How does augment differ from uses with a grouping?
    A `uses` copies a grouping's nodes into the place where the `uses` statement sits, inside the using module's own tree. An `augment` grafts nodes into a tree that another module (or the same one) defines, at a path, leaving that tree's definition untouched. The two combine: an `augment` written as a substatement of `uses`, with a descendant path, extends the grouping's nodes at that point.
  • Can a vendor module add a new parameter to a standard rpc?
    Yes. An rpc's `input` and `output` nodes are legal augment targets, so the augment names the rpc and then its `input`. The new parameter lives in the vendor's namespace. It should stay optional: RFC 7950 says a mandatory input leaf MUST be present in every invocation, so every existing caller that omits it would start failing.
  • Why does a client that ignores the vendor module still see the qos-profile leaf in a reply?
    Augmented nodes are real children of the interface entry, so a read of the entry returns them, tagged with the vendor's namespace (or the `example-vendor-qos:` prefix in JSON). The namespace is what lets that client tell foreign nodes from the `ietf-interfaces` nodes it was written against.

An augment is a labelled sticky note fixed to a page of a published reference book: the book is not reprinted, the page now carries the note wherever the note has been added, and the note bears its own author's name, not the book's.

  • Augmenting ietf-interfaces means publishing a new revision of ietf-interfaces.
  • Nodes added by an augment live in the target module's namespace.
  • An augment can target a leaf, for example to hang sub-leaves under description.
  • In RFC 7951 JSON an augmented leaf uses its plain name, like the target's own leaves.
  • Augment and uses are interchangeable ways to extend a foreign module's tree.