Why does YANG 1.1 require an augment that adds a mandatory configuration leaf to another module's list to carry a when condition, and what breaks without one?
answer
- the client that never heard of you
- create fails validation
- YANG 1.0 forbade it outright
- condition on your own new identity
basics
~20 sAn unconditional mandatory leaf makes every create by a client that knows only the standard module fail validation. YANG 1.1 allows it only under a when that an unaware client never satisfies, such as a vendor-defined interface type.
solid answer
~40 sA client written against `ietf-interfaces` alone creates interfaces with the leaves it knows. If a vendor augment makes `qos-profile` mandatory on every entry, each such create leaves the configuration invalid, the edit or commit fails validation, and the client cannot fix it because it does not know the leaf exists. YANG 1.0 (RFC 6020) therefore banned mandatory nodes in augments of other modules outright; YANG 1.1 (RFC 7950 §7.17) allows mandatory configuration nodes only if the augment is conditional with a `when`, written so unaware clients never meet it. The safe pattern conditions on an interface-type identity defined in the vendor module itself, keeps the expression inside the target entry, and avoids common identities such as `ethernetCsmacd`. Usually the better design is simply an optional leaf.
code
yang · 18 linesmodule example-vendor-qos {
yang-version 1.1;
namespace "urn:example:vendor-qos";
prefix vqos;
import ietf-interfaces { prefix if; }
identity shaped-ethernet {
base if:interface-type;
}
augment "/if:interfaces/if:interface" {
when 'derived-from-or-self(if:type, "vqos:shaped-ethernet")';
leaf qos-profile {
type string;
mandatory true;
}
}
}go deeper
Recall that adding a required field to someone else's model can break clients that never heard of your addition, so YANG restricts it.
Explain what a mandatory node is, when validation runs on running versus candidate, and why YANG 1.0 banned mandatory augmenting nodes while YANG 1.1 allows them under a when.
Show the judgement: choose a condition only aware clients can satisfy, keep it inside the target entry, reject common identities and feature conditions, and usually prefer an optional leaf.
Frame it as a contract decision: vendor requirements that leak into a shared standard tree tax every client in the estate, so a model policy should demand optional extensions unless a new entry type truly needs them.
## The setting A vendor ships `example-vendor-qos`, which augments the standard interface list of `ietf-interfaces` (RFC 8343) with a QoS knob. Someone proposes making that knob **mandatory**: "every interface must have a QoS profile". The question is what that does to the clients already managing these devices, which were written against `ietf-interfaces` alone and have never heard of the vendor module. ## What breaks without a condition A **mandatory node** (RFC 7950 §3) is a leaf, choice, anydata or anyxml node with `mandatory true`, a list or leaf-list with `min-elements` above zero, or a non-presence container holding one of those. In a valid data tree the mandatory constraint is enforced for every such node unless the node or an ancestor has a `when` or `if-feature` that is false (§8.1). So with an unconditional mandatory `qos-profile`: 1. An old client creates a new interface, sending `name`, `type` and `enabled`, the things it knows. 2. The new entry lacks `qos-profile`, so the resulting configuration is invalid. 3. Validation runs at the end of the `<edit-config>` on the running datastore, or at `<commit>`/`<validate>` on the candidate (§8.3.3), and the request fails. The running datastore MUST always be valid, so the server cannot accept it and fix it later. 4. The client cannot repair its request, because it does not know the leaf exists. The standard module did not change, yet a client that was correct yesterday is broken today. The same principle runs through YANG's module update rules (§11): a new revision may add data definitions only if they add no mandatory nodes to existing nodes, unless they are conditional on a new feature. ## How the rule evolved | Version | Rule for an augment of a node in another module | |---|---| | YANG 1.0 (RFC 6020 §7.15) | nodes added by the augmentation MUST NOT be mandatory nodes, full stop | | YANG 1.1 (RFC 7950 §7.17) | mandatory nodes that represent configuration are allowed, but the augmentation MUST be made conditional with a `when` | YANG 1.1 lists this among its changes: "Allow augment to add conditionally mandatory nodes". The `when` is only half the job, because §7.17 adds that care must be taken in writing the expression "so that clients that do not know about the augmenting module do not break". Note the qualifier: the `when` requirement is about configuration. A mandatory node under `config false` state cannot block a client's edit. ## Writing a safe condition The pattern in both RFC 7950 and RFC 9907 §4.19.2 makes the condition depend on something **only a client that knows the vendor module would ever set**: - Define a new interface-type **identity in the same vendor module**, derived from the `interface-type` identity of `ietf-interfaces`. - Put `when 'derived-from-or-self(if:type, "vqos:shaped-ethernet")'` on the augment. An old client never selects that type, so it never creates an entry where the mandatory leaf applies. - Keep the expression inside the target entry. RFC 9907 says the `when` MUST NOT reference data outside the target data node, because the client cannot control external data. - Do not key it to a common identity such as `ethernetCsmacd` from `iana-if-type`. Knowing that common module does not mean a client knows the vendor module, so an old client creating an Ethernet interface would trip the mandatory leaf. - Do not rely on a feature instead. RFC 9907 notes the client cannot control which features a server enables, so a feature condition is not safe for mandatory augmenting nodes. RFC 9907 also warns that the practice is safe only for **creating** resources: a client that replaces an existing entry without knowing the condition can still fail. ## The operator's choices | Option | Old clients | Vendor's goal | |---|---|---| | Optional `qos-profile`, server applies a documented behaviour when absent | keep working | every interface still gets QoS behaviour | | Mandatory under a `when` on a vendor-defined interface type | keep working | QoS is required only where the vendor's type is chosen | | Unconditional mandatory leaf | break on every create | violates RFC 7950 | A `default` statement on the leaf is not an escape hatch: §7.6.4 says `default` MUST NOT be present on a node where `mandatory` is `true`. In practice the optional leaf is usually the right answer; the conditional mandatory leaf is for genuinely new kinds of entry.
- Does the when requirement also apply to mandatory state nodes added under config false?No. RFC 7950 §7.17 requires the `when` for mandatory nodes that represent configuration. State data is produced by the server, not supplied by clients, so a mandatory `config false` leaf cannot make a client's edit fail; it obliges the server to report it.
- Why is a when on ethernetCsmacd not safe for a mandatory augment?Because that identity comes from the common `iana-if-type` module. A client can know `iana-if-type` and `ietf-interfaces` perfectly well without ever having heard of the vendor module, so it will happily create an Ethernet interface and fail on the mandatory leaf it never knew about. RFC 9907 §4.19.2 calls this out explicitly.
saying these in an interview costs you the question
- A mandatory leaf added by augment is harmless because the standard module is unchanged.
- A when on the common ethernetCsmacd identity makes a mandatory augment safe for old clients.
- Giving the mandatory leaf a default value solves the old-client problem.
- YANG 1.0 already allowed conditionally mandatory augments of other modules.
- The server fills in a missing mandatory leaf for clients that do not know it.