skip to content

In a YANG module, how do rpc and notification statements differ from the container and leaf data nodes the module defines?

level: juniorimportance: should knowfreq 13%

answer

  1. what is versus what happens
  2. not in any datastore
  3. input from client, output from server
  4. events the server sends unasked

basics

~10 s

Data nodes describe datastore contents, configuration and state. An rpc defines an operation with optional input and output trees, and a notification defines an event the server sends; neither is stored in a datastore.

solid answer

~40 s

Containers, lists and leaves describe what lives in a **datastore**: configuration clients edit and state the device reports, such as interface counters. An `rpc` is a top-level statement that defines an **operation**: an `input` tree the client sends, where a `mandatory` leaf must appear in every invocation, and an `output` tree the server returns. A `notification` defines an **event** the server sends without being asked. None of these trees is part of a datastore, so `config` inside them is ignored. In NETCONF an rpc becomes a child of `<rpc>` and a notification arrives in `<notification>`; in RESTCONF an rpc is a POST to `/restconf/operations/`. YANG 1.1 adds `action`, an operation tied to one data-node instance.

code

yang · 20 lines
yang
module example-vendor-ops {
  yang-version 1.1;
  namespace "urn:example:vendor-ops";
  prefix vops;
  import ietf-interfaces { prefix if; }
  import ietf-yang-types { prefix yang; }

  rpc clear-counters {
    input {
      leaf interface { type if:interface-ref; mandatory true; }
    }
    output {
      leaf cleared-at { type yang:date-and-time; }
    }
  }

  notification counters-cleared {
    leaf interface { type if:interface-ref; }
  }
}

go deeper

for a junior

Recall the split: data nodes describe configuration and state, an rpc describes an operation with input and output, a notification describes an event the server sends.

for a middle

Explain who sends input and output, what mandatory and default mean in each, and why none of these trees belongs to a datastore.

for a senior

Show modelling judgement: when something should be an operation rather than a writable leaf, and when an operation should be bound to a data node as a YANG 1.1 action.

for a principal

Think about the operations surface of a whole model set: which operations a platform exposes, how they are authorised, and how events replace polling for automation.

## Two halves of a YANG module A YANG module describes two different things, and confusing them is the most common beginner mistake. - **Data nodes** (`container`, `list`, `leaf`, `leaf-list` and their relatives) describe what lives in a **datastore**: configuration a client reads and edits (`config true`) and state the device reports (`config false`), such as the counters under an interface's `statistics` container in `ietf-interfaces`. - **Operation and event schema**: an **`rpc`** defines an operation a client asks the server to perform, and a **`notification`** defines an event the server sends on its own. YANG 1.1 adds **`action`**, an operation tied to a specific container or list instance. Data nodes are about *what is*; rpcs and notifications are about *what happens*. ## The rpc statement: input and output An `rpc` (RFC 7950 §7.14) is a top-level statement in a module. Under it YANG defines two schema nodes, **`input`** and **`output`**, both optional: 1. **`input`** holds the parameters the client sends. A leaf marked `mandatory true` there MUST be present in every invocation. A default value is applied by the server as if the client had sent it. 2. **`output`** holds what the server returns. A mandatory output leaf MUST be present in the reply, and defaults are applied by the client. 3. Neither tree is part of any datastore, so `config` statements inside them are ignored, and nothing an rpc receives is "stored" by YANG. | | `input` | `output` | |---|---|---| | Sent by | client | server | | `mandatory true` means | present in every invocation | present in every reply | | Defaults applied by | server | client | | Part of a datastore | no | no | ## The notification statement A `notification` (§7.16) defines the content of an event. Mandatory leaves must appear in every instance, and like rpc trees it is not datastore content. It can sit at the top level of a module or, in YANG 1.1, inside a container or list, so the event is tied to one entry. ## How each one surfaces - In **NETCONF**, an rpc is a child element of `<rpc>` named after it; with no output the reply is a single `<ok/>`. A notification arrives inside a `<notification>` element with an `<eventTime>` (RFC 5277). - In **RESTCONF** (RFC 8040), an rpc is invoked with a POST to `/restconf/operations/<module>:<rpc>`, a reply without output is `204 No Content`, and notifications are delivered over an event stream. - In a **tree diagram** (RFC 8340), rpcs and actions carry the `-x` flag, input parameters `-w`, output and notification parameters `ro`, and notifications `-n`. The wire mechanics belong to the protocol subjects; the point here is that one schema drives both. ## A worked example: interface counters The counters themselves are state leaves (`config false`) in `ietf-interfaces`. A vendor that wants a "clear counters" operation and an event announcing it writes an `rpc` and a `notification`: - `clear-counters` takes a mandatory `interface` input of type `if:interface-ref` and returns `cleared-at`. - `counters-cleared` tells subscribers which interface was cleared. - Nothing in either is configuration: clearing counters is something that happens on the device, not a value to store, which is exactly why it is an rpc and not a writable leaf. A YANG 1.1 module could instead attach the operation to each interface entry as an `action`; choosing between the two is a design decision of its own. ## Rules that carry over, and rules that do not Operation and event trees reuse the data-node vocabulary, which is why they are easy to mistake for data: - They are built from the same statements: `leaf`, `container`, `list`, `choice`, `uses` and the rest can all appear inside `input`, `output` and `notification`. - YANG 1.1 allows `must` constraints in `input`, `output` and `notification`, so a model can say, for example, that an end time in the input must follow the start time. The constraint is checked against the invocation, the reply or the event, not against a datastore. - A `when` inside an input or output tree means the node MUST NOT be present when the condition is false. - `config` is meaningless there and ignored, because nothing in these trees is stored. - They can be extended by other modules: `input`, `output` and `notification` nodes are legal targets for `augment`, so a vendor can add an optional field to a standard notification or a standard rpc's input without editing the standard module.

  • If an rpc changes configuration, does its input become configuration?
    No. The input tree is never part of a datastore; RFC 7950 says `config` statements inside it are ignored. An rpc may well change a datastore as a side effect, but what it changes is the data nodes of some module, validated as configuration, not the rpc's parameters.
  • Why model clearing counters as an rpc rather than a writable leaf?
    Clearing is something that happens, not a value that should persist in configuration. A writable `clear` leaf would sit in the datastore, could be copied to startup and replayed after a reload, and its meaning after the first write is unclear. An operation with input and output says exactly what is requested and what came back.

saying these in an interview costs you the question

  • An rpc's input parameters are stored in the running configuration.
  • A notification is just a config false container the client polls.
  • Mandatory in an rpc's output means the client must send that leaf.
  • An rpc can be defined inside a container, next to the data it acts on.