In YANG, how does a must statement differ from a when statement, and what happens to the data when each evaluates to false?
answer
- an error versus a disappearance
- error-message and error-app-tag
- must-violation by default
- unknown-element, or silent deletion
basics
~20 sA false YANG must is a validation error: the edit is refused with the must's error-message and error-app-tag. A false when means its node does not apply: writes to it fail, and an existing instance is silently deleted.
solid answer
~40 s`must` declares a constraint on valid data: an XPath expression, converted to a boolean, that MUST be true for every instance of the node it sits on. If it is false the data is invalid and a NETCONF server answers `operation-failed`, with the statement's `error-app-tag` (default `must-violation`) and its `error-message`. `when` makes its parent node conditional: while the expression is false the node may not exist. A request that writes such a node gets `unknown-element`; an edit elsewhere that turns the condition false makes the server delete the node, with no error. In a BGP model, a `must` rejects a hold time of 1 or 2 seconds, while `when "../peer-type = 'external'"` keeps `ebgp-multihop` only on external peers. RFC 9907 sums it up: `must` for value rules spanning several nodes, `when` for conditional composition.
code
yang · 18 lineslist neighbor {
key "address";
leaf address { type inet:ip-address; }
leaf peer-type {
type enumeration { enum internal; enum external; }
}
leaf ebgp-multihop {
when "../peer-type = 'external'";
type uint8 { range "1..255"; }
}
leaf hold-time {
type uint16;
must ". = 0 or . >= 3" {
error-message "hold-time must be 0 or at least 3 seconds";
error-app-tag "hold-time-too-short";
}
}
}go deeper
Remember the split: must is a rule the data must satisfy, when decides whether a node exists at all.
Explain the false cases precisely: must gives operation-failed with must-violation or the model's own app tag; when deletes the node, or answers unknown-element to a write.
Show judgement about silent deletion: when an operator would rather be told than lose a value, use a must on the conditional node, and put single-leaf rules in the type.
Treat constraints as a contract: error-app-tags are what automation matches on, and published revisions may only relax a must or when, so choose the strictness carefully.
## Two statements, two meanings Both `must` and `when` take an XPath 1.0 expression, both are evaluated against the data tree, and both can refer to other nodes. That is where the similarity ends. RFC 9907, the YANG authoring guidelines, puts the difference bluntly: a false `when` silently removes data and is not an error; a false `must` is a datastore validation error. | | `must` | `when` | |---|---|---| | Meaning | a condition valid data has to satisfy | the parent node is valid only while the condition holds | | Result when false | the data is invalid; the edit or commit is refused | the node may not exist; an existing instance is deleted | | What the client sees | `operation-failed`, the statement's `error-app-tag` (default `must-violation`) and its `error-message` | nothing for a deletion; `unknown-element` if the client writes the node | | Substatements | `error-message`, `error-app-tag`, `description`, `reference` | `description`, `reference` | | Context node, on a data node | the instance of the node carrying it | a dummy node standing in for the node | ## must: a rule the data has to satisfy RFC 7950 §7.5.3 calls `must` a formal constraint on valid data. When a datastore is validated, each `must` is conceptually evaluated for every instance of the node it sits on, the result is converted to a boolean, and every one MUST be true. Comparisons use each value's canonical form. Two substatements turn a failure into something an operator can act on: - **`error-message`** — a string the server passes back as `<error-message>` in the NETCONF `<rpc-error>`; - **`error-app-tag`** — a string passed back as `<error-app-tag>`, which a client program can match on. Without an `error-app-tag`, RFC 7950 §15.4 fixes the reply as `error-tag` `operation-failed` with `error-app-tag` `must-violation`. YANG 1.1 also allows `must` inside `input`, `output` and `notification`, so operation parameters and notification content can be constrained the same way. ## when: a node that exists only in some cases RFC 7950 §7.21.5 says `when` makes its parent data definition conditional. Three behaviours follow from the rest of the specification: 1. If a request carries data for a node whose `when` is false, the server replies `unknown-element` (§8.3.1 and §8.3.2). 2. If an edit changes some other node so that a `when` becomes false, the server deletes the conditional node itself (§8.2) — no error, no message. 3. While a `when` is false, the node's `mandatory`, `min-elements` and `max-elements` rules are not enforced (§8.1). A key leaf of a list MUST NOT have a `when`, and `when` expressions MUST NOT depend on each other in a circle; one that references a node with its own `when` is evaluated after it. A `when` attached to an `augment` follows its own context rule and belongs with augmentation. ## The BGP neighbour, both ways In the code example, `hold-time` carries a `must` that rejects 1 and 2 seconds — RFC 4271 requires a BGP hold time of either zero or at least three seconds — and `ebgp-multihop` carries a `when` so it exists only for external peers. Trace two edits: 1. A client sets `hold-time` to 2. When the configuration is validated, `. = 0 or . >= 3` is false; the server replies `operation-failed` with app tag `hold-time-too-short` and the message "hold-time must be 0 or at least 3 seconds", and the change is not applied. 2. A client changes `peer-type` from `external` to `internal` on a neighbour that has `ebgp-multihop 2`. The `when` turns false, the server deletes `ebgp-multihop`, and the edit succeeds. ## Choosing between them - Use **`must`** when a value is *wrong*: an operator made a mistake and deserves a reason. RFC 9907 recommends it for value restrictions that involve more than one data node, such as an end time that must follow a start time. - Use **`when`** when a node *does not apply*: multihop settings on an internal peer are irrelevant rather than an error. RFC 9907 recommends it, together with `augment` or `uses`, for conditional composition, with conditions based on static properties such as list keys. - If silently losing a value would surprise operators, a `must` on the conditional node (`../peer-type = 'external'`) refuses the edit instead and leaves the decision to them. - A rule about one leaf's own value can often be a type restriction instead, such as a `range` on `hold-time`; that is checked earlier, as the payload is parsed. - RFC 7950 §11 lets a later revision of a published module remove or relax a `must` or `when`; tightening one in place is not an allowed revision.
- Is a false YANG when ever reported to the client as an error?The condition itself is not an error: if an edit elsewhere turns it false, the server deletes the conditional node and the edit succeeds (RFC 7950 §8.2). Writing data into a node whose `when` is already false is an error, though: the server replies `unknown-element`, at parse time or during `<edit-config>` processing. `when` has no `error-message` substatement, so no custom text is ever attached.
- Why might a reviewer suggest replacing the hold-time must with a range on the leaf's type?The rule concerns one leaf's own value, which a type restriction such as `range "0 | 3..65535"` expresses directly. A range is checked as the payload is parsed, so the client gets `invalid-value` at once, and it can carry its own `error-message` and `error-app-tag`. RFC 9907 reserves `must` for restrictions that involve more than one node, such as keepalive shorter than hold time.
- A later revision of the published module tightens the hold-time must to require at least 9 seconds. Is that allowed?No. RFC 7950 §11 allows a revision to remove a `must` or relax its constraint, never to tighten it, because a configuration valid under the old revision could become invalid under the new one. A stricter rule needs a new definition with a new identifier.
A when is the section of a form that only appears when you tick "business customer": untick the box and the section, with whatever you typed in it, is gone without complaint. A must is the check that refuses to submit the form until two fields agree, and tells you why.
saying these in an interview costs you the question
- must and when are interchangeable; when just gives a friendlier error.
- A false when returns its own error-message to the client.
- When a when turns false, the server keeps the node but ignores it.
- A failing must with no error-app-tag returns no app tag at all.
- A must on an optional leaf fires when that leaf is left out.