In YANG, how does a vendor module use augment to add a QoS leaf to the standard ietf-interfaces list without editing that module?
answer
- graft, don't edit
- import plus absolute target path
- whose namespace owns the new leaf
- module-name:leaf in RFC 7951 JSON
basics
~10 sThe 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 sThe 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 linesmodule 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
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.
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.
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.
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.
saying these in an interview costs you the question
- 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.