Content
client.content implements the Content layer of NETCONF (RFC 6241 §1.2), which focuses attention on the configuration and state data itself, rather than the Operations layer protocol operations. Although the layer is specified in RFC 6241, its design is not, and so the Content layer presented here is this library's determination of a useful, high-level interface. If you want to work closer to the NETCONF protocol itself, see Operations instead.
The highlighted steps are where the client changes the data's form: paths and JSON become XML on the way to the server, and the XML that comes back becomes JSON.
In this implementation, you name the data by the YANG path definition specified in RFC 7950 §9.13, and the library works out the filters, edits and sequences of operations from what the server advertises, adjusted by a device profile if you use one. You can read and write any YANG model the server advertises. You don't need schema files, generated code or XML.
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
// 'uplink', or undefined if not set
await client.content.readValue(`${IF}/description`);
// RFC 7951 JSON from running, typed by the YANG schema
await client.content.read(IF);
// config and state, with <get>
await client.content.read(IF, { source: 'config+state' });
// the matching XML elements, as the server sent them
await client.content.read(IF, { format: 'xml' });
// merge a value into the config
await client.content.set(`${IF}/description`, 'uplink');
// delete an entry; fine if it's already gone
await client.content.remove(
'/ietf-interfaces:interfaces/interface[name="eth9"]',
);Methods
| Method | What it does | Sends |
|---|---|---|
read() | the nodes a path selects, as XML or JSON | <get-config> or <get> |
readValue() | the value of the first leaf a path selects | <get-config> or <get> |
set() | sets one value | the device's workflow |
remove() | deletes one node, if it exists | the device's workflow |
configure() | applies several edits in one <edit-config> | the device's workflow |
invoke() | invokes the RPC or YANG 1.1 action a path names, with JSON input and output | the RPC, or <action> |
checkEdits() | checks a configure() callback without applying it | at most a YANG library read |
compareDatastores() | how two configuration datastores differ | two <get-config> |
getCandidateChanges() | what a commit would apply | two <get-config> |
datastores() | the datastores the server has | at most a YANG library read |
modules() | a datastore's YANG modules and features | at most a YANG library read, and schema reads with declared |
toJson() | converts YANG data from XML to RFC 7951 JSON | schema reads only |
toXml() | converts RFC 7951 JSON to XML | schema reads only |
expandPath() | the path a named path stands for | nothing |
resolvePath() | a path's steps, with their namespaces | nothing |
toXPath() | a path as an XPath filter | nothing |
readFilter() | the filter read() would send | nothing |
namedPathTemplate() | a named path's parameters | nothing |
moduleNamespace() | a module's namespace | nothing |
moduleOf() | a namespace's module | nothing |
moduleNamespaces() | every module the session knows, with its namespace, or one source's whole list | nothing |
moduleNamespacesInfo() | the same, with where each namespace came from, or one source's whole list | nothing |
loadModules() | learns module namespaces from the YANG library | a YANG library read, once per session |
Extensions add their own readers under their id, such as client.content.monitoring: see Extensions' readers.
Each method that sends something also takes { timeout, signal }. The API reference has every method's full signature.
Paths
Path syntax
Paths are YANG instance identifiers (RFC 7950 §9.13), with module names in place of prefixes, as in YANG's JSON encoding (RFC 7951):
/ietf-interfaces:interfaces/interface[name="eth0"]/description
/nokia-conf:configure/port[port-id="1/1/2"]/description
/example:routes/route[prefix="10.0.0.0/8"][vrf="blue"]- A path is a series of steps separated by
/, one for each node (RFC 7950 §9.13). The steps of/ietf-interfaces:interfaces/interface[name="eth0"]/descriptionareietf-interfaces:interfaces,interface[name="eth0"]anddescription. - The first step names its module before a colon:
ietf-interfaces:interfacesis theinterfacesnode of theietf-interfacesmodule. Later steps take the module from the step before them, unless they name another one, as an augmented node does: in/ietf-interfaces:interfaces/interface[name="eth0"]/ietf-ip:ipv4,interfacecomes fromietf-interfacesandipv4fromietf-ip. This is the JSON encoding's rule (RFC 7951 §6.11). The XML encoding puts a prefix on every step instead. - List entries are selected by their keys, in square brackets, with a predicate for each key (RFC 7950 §9.13). Write the keys in the order the YANG model gives them: the standard allows any order, but NETCONF's XML encoding sends keys in the model's order (RFC 7950 §7.8.5), and the client builds the XML in the order you write.
- A path that starts with
@is a named path from the device profile:client.content.readValue('@systemName'). A named path can take parameters:@ifDescription(eth0). See Named paths with parameters. Named paths are this library's convention, not part of any RFC.
Syntax errors are reported with their position (PathError) before anything is sent.
Reading
read(path) resolves with the nodes the path selects, as JSON by default or, with format: 'xml', as every element selected (an empty array if none). readValue(path) resolves with the first one's value, or undefined if there is none.
source picks where the data comes from:
source | Reads | With |
|---|---|---|
'running' (default), 'candidate', 'startup' | that configuration datastore | <get-config> |
'config+state' | running configuration and state | <get> |
'operational' is refused with a TypeError. It names the NMDA <operational> datastore, which <get> doesn't read: use the nmda extension's getData() for it.
The other getConfig() options, such as the with-defaults extension's withDefaults, are passed on.
JSON
By default, read() resolves with the target node as RESTCONF returns it (RFC 8040), in RFC 7951 JSON typed by the server's YANG schema. The node's module-qualified name is the only member, and its value is the list's matching entries (as an array), the container (as an object), or the leaf's typed value. Nothing matching gives {}. readValue() resolves with the leaf's typed value:
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
await client.content.read(IF);
// { 'ietf-interfaces:interface': [{ name: 'eth0', enabled: true, … }] }
await client.content.read(`${IF}/enabled`);
// { 'ietf-interfaces:enabled': true }
// true, a boolean
await client.content.readValue(`${IF}/enabled`);This is the Content layer's default. The Operations layer's reads (client.ops.get(), getConfig()) default to XML, because they return what the server sent.
Key predicates match a key by its value, whatever its JSON type: [mtu="1500"] matches the number 1500. The conversion rules, where the schema comes from and what happens without one are in JSON and YANG.
Without a schema
Turning a path into a request needs no schema, but turning the server's XML reply into typed JSON does. The library takes each module's text from connect({ yang: { modules } }), the device profile, the IETF modules it bundles, or the server's <get-schema>. When none of them has a module the data needs (on a device without <get-schema>, for example), the JSON is converted schema-less. It then differs from typed JSON: for example, values are text, and a list with one entry is not an array. A warning event says so, and suggests supplying the modules with yang.modules. Why the schema matters explains what a schema-less conversion can't tell you, and Where the schema comes from how to supply one.
format: 'xml' reads the data as the server sent it, which needs no schema at all. Values are text, and readValue() gives the trimmed text:
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
// the <description> element(s)
await client.content.read(`${IF}/description`, { format: 'xml' });
// 'true', a string
await client.content.readValue(`${IF}/enabled`, { format: 'xml' });With requireSchema, a read that can't be typed rejects instead, and its error suggests format: 'xml'.
Reading on devices that filter badly
read() sends a subtree filter built from the path, then selects the matching elements locally. Some devices can't handle subtree filters, or only some of them. A profile's subtreeFilter quirk changes what read() sends, while the result stays the same. client.content.readFilter(path) shows the filter read() would send, without sending it.
Writing
set(path, value) merges one value into the configuration, and remove(path) deletes one node, doing nothing if it's already gone. Each is a one-edit configure(), and takes the same options.
A single change
set() sets one value, merging it into the configuration:
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
await client.content.set(`${IF}/description`, 'uplink');Running it again changes nothing: a merge of the value already there succeeds.
Several changes at once
configure() collects edits and applies them as one <edit-config>:
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
const ETH1 = '/ietf-interfaces:interfaces/interface[name="eth1"]';
await client.content.configure((txn) => {
// merge
txn.set(`${IF}/description`, 'uplink');
// replace the node and everything below it
txn.replace(`${ETH1}/enabled`, true);
// fails if it exists
txn.create('/ietf-system:system/location', 'rack 1');
// fails if it's missing
txn.delete(`${ETH1}/description`);
// fine if it's missing
txn.remove('/ietf-interfaces:interfaces/interface[name="eth9"]');
});Run it a second time and it fails, as it should: location now exists, and eth1 has no description left to delete.
A value can be a string, number or boolean (it becomes text), an XmlElement or array of them (they become children), or null (an empty element).
Inside the callback the edit methods check only path syntax. An unknown module rejects configure() itself, before anything is sent. A callback that makes no edits sends nothing.
JSON edits
txn.merge(json) and txn.replace(json) add whole subtrees as RFC 7951 JSON, in the same <edit-config> as the path edits. replace marks each top-level member with the NETCONF replace operation:
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
await client.content.configure((txn) => {
txn.set(`${IF}/description`, 'uplink');
txn.merge({
'ietf-system:system': {
contact: 'noc@example.net',
location: 'rack 2',
},
});
});The JSON is converted with the schema of the workflow's edit target, by the rules in Writing JSON, including RFC 7952 metadata for deletes and inserts. A conversion problem rejects configure() (and checkEdits()) before anything is locked or sent. Several merge() calls on the same top-level member are combined, but one top-level node can't be edited both by a path and as JSON, or both merged and replaced. The json option of configure() takes the same settings as json on editConfig().
Checking edits first
checkEdits() takes the same callback as configure() and runs every check configure() makes before sending: path syntax, unknown modules and named paths, two edits to the same node, a value given to remove, and the JSON conversion. It rejects as configure() would, but sends no edit and takes no lock. It may read the YANG library once, to resolve a module only the library lists (see Where namespaces come from).
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
await client.content.checkEdits((txn) => {
txn.set(`${IF}/description`, 'uplink');
});It takes editTarget and json, which pick the schema for JSON edits.
Edits the target can't hold
Under NMDA each datastore has its own schema, and a module can be in one but not another: a state module only operational implements, for example. A path through such a module can't be written to running or the candidate. When the session has read a YANG library that lists datastores, configure(), set(), remove() and checkEdits() reject a path whose module the library implements in another datastore's schema but not in the edit target's, with a PathError, before anything is locked or sent:
await client.content.set('/acme-state:counters/reset', true);
// PathError: configure: /acme-state:counters/reset is in module
// acme-state, which the server's YANG library implements in
// operational but not in running, the datastore this edit goes toOnly that evidence counts. A module the library doesn't implement in any datastore, such as one you or the device profile name for a device whose library is incomplete, is left for the server to accept or refuse. The check follows capabilityCheck: with 'warn' the edit is sent with a warning event, and with 'off' there's no check.
How changes are applied
set(), remove() and configure() follow the device's workflow. Each part comes from the call's options, then the device profile, then what the server advertises:
| Default | |
|---|---|
editTarget | candidate if the server has :candidate, otherwise running |
lock | true |
validate | true on candidate if the server has :validate |
commit | true on candidate |
On a candidate workflow the steps are lock, discard stale changes, edit, validate, commit and unlock, using withCandidate(). If anything fails, the candidate is discarded and the locks released, and the call rejects with a TransactionError naming the failed step. If another session holds a lock, you get a LockDeniedError with the holder's session-id.
const pending = await client.content.set(
'/ietf-system:system/contact',
'noc@example.net',
{
// each request as it succeeds
onStep: (step) => console.log(step.operation, step.datastore),
// a confirmed commit; see Transactions
confirmed: { timeout: 120 },
},
);
// make the change permanent (set() gives a PendingCommit
// only with confirmed)
await pending?.confirm();With confirmed, the call resolves with a PendingCommit to confirm or cancel. confirmed needs a candidate workflow that commits.
Advanced paths
Named paths with parameters
A device profile's named paths may hold {{parameter}} placeholders, so one name covers every entry of a list. The lab device's built-in lab profile has these, so the examples below run in the REPL:
"paths": {
"interface":
"/ietf-interfaces:interfaces/interface[name={{ifName}}]",
"ifDescription":
"/ietf-interfaces:interfaces/interface[name={{ifName}}]/description"
}Give values by position (in the order the parameters first appear) or by name. namedPath() builds the reference, quoting the values for you:
import { namedPath } from '@node-net/netconf';
await client.content.readValue('@ifDescription(eth0)');
await client.content.readValue('@ifDescription(ifName=eth0)');
// '@ifDescription(ifName="eth0")'
const ref = namedPath('ifDescription', { ifName: 'eth0' });
await client.content.readValue(ref);With several parameters, position follows the order they first appear in the template. On a device whose profile has "route": "/example:routes/route[prefix=][next-hop=]":
import { namedPath } from '@node-net/netconf';
await client.content.read('@route(10.0.0.0/8, 192.0.2.1)');
// quoting done for you: the prefix holds a /
const route = namedPath('route', {
prefix: '10.0.0.0/8',
nextHop: '192.0.2.1',
});
await client.content.read(route);
// every next hop for that prefix (see below)
await client.content.read('@route(10.0.0.0/8)');A read may leave out a parameter that is a predicate's whole value. The predicate is dropped, so the path selects every entry:
// every interface
await client.content.read('@interface');
// every interface's description
await client.content.read('@ifDescription');set(), remove() and configure() need every parameter: an edit without its list keys isn't the edit you meant, so it fails with a PathError before anything is sent.
More of the path can follow a reference, so one named path for a list entry covers everything under it:
await client.content.set('@interface(eth0)/description', 'uplink');
await client.content.read('@interface(eth0)/enabled');
// every interface's description
await client.content.read('@interface/description');The rest of the path starts with /, and its steps take their module from the step before, as in any path. With namedPath(), append it to the result:
import { namedPath } from '@node-net/netconf';
const ifPath = namedPath('interface', { ifName: 'eth0' });
await client.content.read(`${ifPath}/description`);This is also why a named path's name can't hold /, and it can't start with @ either. namedPath() accepts the name with or without its @.
A placeholder written anywhere else must always be given, even on a read. That covers part of a quoted value, or a step's name, as in these two of the lab profile's paths:
"paths": {
"port":
"/openconfig-platform:components/component[name=\"port-{{port}}\"]",
"systemLeaf": "/ietf-system:system/{{leaf}}"
}// name="port-eth0"
await client.content.read('@port(eth0)/config');
// /ietf-system:system/hostname
await client.content.readValue('@systemLeaf(hostname)');
// a PathError: '@port needs port: …'
await client.content.read('@port').catch((err) => err.message);Where namespaces come from
A YANG path names YANG modules, but the underlying NETCONF protocol needs XML namespaces. The client looks a module up in this order:
- the
namespacesparameter on the connectconnect({ namespaces: { 'my-module': 'urn:…' } }), - the device profile's
namespaces, - the server's
<hello>capabilities, - a cache of the server's YANG library (RFC 8525, or the older RFC 7895), if the session has already read it,
- the server's YANG library, fetched now if no step above knows the module. The session caches what it fetches, so from then on step 4 answers.
What you set beats what the device profile sets, which beats what the server says, so you can correct a server that gives a module the wrong namespace. A namespace you or the profile give that differs from the server's is logged at debug level.
Steps 1 to 3 are known when the session opens, and the YANG library only answers modules none of them knows. Reading the library therefore never changes a namespace the client has already used. It only adds modules that were unknown before.
YANG 1.1 modules aren't listed in the hello (RFC 7950 §5.6.4), though some servers list them anyway, so the YANG library is usually how they're found. client.content.moduleNamespace(name) does steps 1 to 4, and the JSON conversion uses the same order. client.content.moduleOf(namespace) looks the other way, from a namespace to its module, which is how identities and paths are named.
read(), set(), remove(), configure() and checkEdits() read the YANG library by themselves when they need it. The methods in Path tools are synchronous, so for a module only the library lists, call await client.content.loadModules() first. It resolves with moduleNamespaces() (below), and sends nothing on a server without a YANG library. The library is read once per session, shared with datastores(), modules() and the yang-library extension. loadModules({ refresh: true }) reads it again.
Seeing every namespace
moduleNamespaces() is every module the session knows, mapped to the namespace moduleNamespace() gives it. It sends nothing. Modules from steps 1 to 3 come first, then the ones only the YANG library lists, once the session has read it:
client.content.moduleNamespaces();
// FrozenMap(17) [Map] {
// 'iana-if-type' => 'urn:ietf:params:xml:ns:yang:iana-if-type',
// 'ietf-netconf' => 'urn:ietf:params:xml:ns:netconf:base:1.0',
// …
// }On the lab device that's 17 modules from the hello. Its YANG 1.1 modules, such as ietf-interfaces, join them once the session reads the YANG library.
moduleNamespacesInfo() adds where each namespace came from (given, profile, hello or library, for steps 1 to 4):
await client.content.loadModules();
client.content.moduleNamespacesInfo().get('ietf-interfaces');
// {
// namespace: 'urn:ietf:params:xml:ns:yang:ietf-interfaces',
// source: 'library'
// }When a later source gave the module a different namespace, overrides lists it, so you can see what you or the device profile corrected. On a device whose profile corrects the namespace its hello gives acme-system:
client.content.moduleNamespacesInfo().get('acme-system');
// {
// namespace: 'urn:acme:system',
// source: 'profile',
// overrides: [{ source: 'hello', namespace: 'urn:acme:sys' }],
// }With source, moduleNamespacesInfo() gives that source's whole list instead: every module it names, with the namespace it gives, whether or not an earlier source beats it. These are the lists for the five steps:
const ns = client.content;
// 1. connect({ namespaces })
ns.moduleNamespacesInfo({ source: 'given' });
// 2. the device profile's namespaces
ns.moduleNamespacesInfo({ source: 'profile' });
// 3. the server's hello
ns.moduleNamespacesInfo({ source: 'hello' });
// 4. the YANG library, if the session has read it; empty if not
ns.moduleNamespacesInfo({ source: 'library' });
// 5. read the library now, then as step 4
await ns.loadModules();
ns.moduleNamespacesInfo({ source: 'library' });The hello's entry for acme-system above is { namespace: 'urn:acme:sys', source: 'hello' }, though the profile's namespace is the one used. In a source's own list, overrides lists only where the source disagrees with itself, such as two YANG library module sets giving a module different namespaces.
moduleNamespaces({ source }) gives the same list without the sources, mapping each module to the namespace that source gives it.
Namespaces span every datastore
None of these methods takes a datastore. A module's namespace belongs to the module, so it's the same in every schema the module is in, and one lookup serves every datastore. The YANG library's entries come from every datastore's schema and module set, so moduleNamespaces() can list a module that only operational has. To see which modules one datastore has, use modules({ datastore }).
Whether a datastore has a module matters when you write to it. set(), remove(), configure() and checkEdits() check each path against the edit target's schema: see Edits the target can't hold.
Path tools
These methods send nothing. They throw a PathError for a malformed path, an unknown module or an unknown name.
expandPath() shows the path a reference stands for, filling in its parameters as a read does:
client.content.expandPath('@ifDescription(eth0)');
// '/ietf-interfaces:interfaces/interface[name="eth0"]/description'
client.content.expandPath('@ifDescription');
// '/ietf-interfaces:interfaces/interface/description'toXPath() turns a path into an XPath filter, declaring the namespaces for you. Use it as a filter for get(), or anywhere else that takes XPath, such as a partial-lock select:
// ietf-interfaces is YANG 1.1: read the library first (see above)
await client.content.loadModules();
client.content.toXPath(
'/ietf-interfaces:interfaces/interface[name="eth0"]',
);
// {
// type: 'xpath',
// select: "/ietf-interfaces:interfaces/ietf-interfaces:interface"
// + "[ietf-interfaces:name='eth0']",
// namespaces: {
// 'ietf-interfaces': 'urn:ietf:params:xml:ns:yang:ietf-interfaces'
// }
// }resolvePath() parses a path and resolves each step's module, for code that works with paths itself:
await client.content.loadModules();
client.content.resolvePath(
'/ietf-interfaces:interfaces/interface[name="eth0"]/description',
);
// [
// { name: 'interfaces', moduleName: 'ietf-interfaces', ns: '…', … },
// { name: 'interface', keys: [{ name: 'name', value: 'eth0' }], … },
// { name: 'description', moduleName: 'ietf-interfaces', … },
// ]Each step has its name, its moduleName and namespace (ns), whether written on the step or taken from the one before, and its list keys.
namedPathTemplate(name) returns a named path's template from the profile, or undefined when there is none. Its params are the parameter names, in the order they first appear, and optional holds the ones a read may leave out. The CLI uses it to complete and check named paths.
The same parsing is available without a client: parsePath() parses a path's syntax, pathXPath() turns resolved steps into an XPath filter, and compileNamedPath() checks a named-path template.
Comparing datastores
compareDatastores({ source, target }) lists how two of running, candidate and startup differ: the changes that turn source into target. getCandidateChanges() is the same comparison from running to the candidate, so it lists what a commit would apply.
await client.content.set('/ietf-system:system/location', 'rack 2');
// what a reboot would lose
const unsaved = await client.content.compareDatastores({
source: 'startup',
target: 'running',
});
for (const c of unsaved) {
console.log(c.operation, c.path, c.previous, '→', c.value);
}
// on a fresh lab device, whose startup matches running:
// create /ietf-system:system/location undefined → rack 2Each change has:
operation:create(only in the target),delete(only in the source),replace(a leaf's value changed) ormove(an entry of an ordered-by-user list or leaf-list changed place)path: the node's RFC 7951 data path, with list entries named by their keysvalue: the node as it is in the target, andprevious: as it is in the source, as RFC 7951 JSON (a leaf's typed value, or an object for a container or list entry)position, for a created or moved entry of an ordered-by-user list:{ where: 'first' }or{ where: 'after', anchor }, whereanchoris the path of the entry before it
List entries are matched by their keys, so adding one interface is one create, whatever its position. Nothing inside a created or deleted node is listed separately. filter limits the comparison to part of the configuration, as on getConfig().
Both datastores are read with <get-config> and compared by the client, so this works on any server, with no RFC 9144 compare support needed. It needs the server's YANG schema to match list entries: when the data can't be typed, it rejects with a SchemaUnavailableError rather than guessing (see Where the schema comes from). A datastore the server doesn't advertise is refused with a CapabilityError.
Another session can change either datastore between the reads. To compare under locks before committing, use txn.getCandidateChanges() inside withCandidate().
Device information
Device datastores
client.content.datastores() lists the datastores the server has, whether or not it supports NMDA:
await client.content.datastores();
// {
// source: 'yang-library',
// datastores: [
// { name: 'ietf-datastores:running', schema: 'complete' },
// { name: 'ietf-datastores:candidate', schema: 'complete' },
// { name: 'ietf-datastores:startup', schema: 'complete' },
// { name: 'ietf-datastores:intended', schema: 'complete' },
// { name: 'ietf-datastores:operational', schema: 'complete' }
// ]
// }The list always comes from one source, and source says which:
source | When | The list |
|---|---|---|
'yang-library' | The server advertises :yang-library:1.1 (NMDA, RFC 8525) | Its /yang-library/datastore entries, in its order, each with the schema it uses. These can include datastores beyond the standard five, such as factory-default |
'capabilities' | Any other server (no YANG library, or only :yang-library:1.0), or one whose library lists no datastores | running, then candidate with :candidate, then startup with :startup (RFC 6241). Nothing is sent |
Both use the capabilities after the device profile's corrections. The library is read once per session, the same read the path API and the yang-library extension use. refresh: true reads it again.
Device modules and features
client.content.modules() lists the YANG modules the server has for a datastore (default running), with the features it supports:
const { source, schema, modules } = await client.content.modules({
module: 'ietf-netconf',
});
console.dir(modules, { depth: null });
// source: 'yang-library', schema: 'complete'
// [{
// name: 'ietf-netconf', revision: '2011-06-01',
// namespace: 'urn:ietf:params:xml:ns:netconf:base:1.0',
// conformance: 'implement',
// features: ['candidate', 'confirmed-commit', …, 'xpath'],
// deviations: [], submodules: [], locations: []
// }]A feature belongs to its module: xpath in ietf-netconf and xpath in ietf-subscribed-notifications are different features. Which features a server supports can differ between datastores, because under NMDA each datastore has a schema of its own (the configuration datastores always share one; operational may differ). Pass datastore for another datastore, or schema to name a YANG library schema directly. module keeps one module by name.
As with datastores(), the list comes from one source and is never merged:
source | When | The list |
|---|---|---|
'yang-library' | The server advertises :yang-library:1.1 or :yang-library:1.0 | The modules of the datastore's schema. A library without datastores (RFC 7895, or a 1.1 library listing none) has one schema, which serves every datastore. A datastore or schema the library doesn't list is rejected |
'capabilities' | Any other server, or one whose library lists no modules | The module capabilities in the hello. Nothing is sent |
On a server with a YANG library, the module capabilities in its hello are ignored: YANG 1.1 modules never appear there, so the library is the complete list. The hello stays the authority for protocol capabilities such as :candidate.
Implemented modules come first, then the import-only ones (conformance: 'import'), whose definitions are used only by modules that import them.
Features a server doesn't support
A server only reports the features it supports. To also see the ones it doesn't, the module's YANG source is needed. declared: true reads it (from the schema sources the JSON conversion uses, <get-schema> included), compiles it, and adds every feature it declares:
const { modules } = await client.content.modules({
module: 'ietf-netconf',
declared: true,
});
const [netconf] = modules;
console.log(netconf.declared);
// [
// { name: 'writable-running', supported: true },
// …,
// { name: 'url', supported: false },
// { name: 'xpath', supported: true }
// ]
// features the server reports but the source doesn't declare
netconf.undeclared;
// []This reads and compiles source, so it costs more than the list itself. A module whose source can't be found has no declared, and a session warning names it.
Converting between XML and JSON
toJson() and toXml() convert YANG data by the same rules and schemas as JSON reads and JSON config, for data that didn't come from (or isn't going to) a read or edit:
toJson(element, { datastore, scope })converts any element holding YANG data to JSON: the result ofclient.session.rpc(), a transaction'sgetConfig(), or a notification's content.datastore(default'operational') picks the schema. A parsed element carries the prefixes declared above it, soscopeis only for an element built withx()whose values use prefixes declared elsewhere.toXml(json, { datastore, filter })returns the elements an edit would send, or withfilter: true, subtree-filter content.datastoredefaults to'running'. Extensions get it asctx.toXml.
import { NETCONF_NS, x } from '@node-net/netconf';
const reply = await client.session.rpc(x('get', { xmlns: NETCONF_NS }));
const json = await client.content.toJson(reply.data!);Neither sends anything except the schema reads it needs. The rules are in JSON and YANG.
Extensions' readers
An extension that decodes data puts its readers under its id: client.content.monitoring.sessions(), client.content.yangLibrary.load(), client.content.withDefaults.basicMode and others. Each is listed with its extension, and Reads as operations shows how they are also run by name.
Errors
A path that can't be parsed, names an unknown module or named path, or is missing a parameter rejects with a PathError before anything is sent. Edits that the server refuses reject with a TransactionError, and JSON that doesn't match the schema with a YangDataError. The errors of the operations underneath, such as RpcError and TimeoutError, come through unchanged. See Errors.