This document defines a mechanism to combine YANG modules into the schema defined in other YANG modules.
Modularity and extensibility were among the leading design principles of the YANG data modeling language. As a result, the same YANG module can be combined with various sets of other modules and thus form a data model that is tailored to meet the requirements of a specific use case. Server implementors are only required to specify all YANG modules comprising the data model (together with their revisions and other optional choices) in the YANG library data (^RFC7895^, and Section 5.6.4 of ^RFC7950^) implemented by the server. Such YANG modules appear in the data model “side by side”, i.e., top-level data nodes of each module - if there are any - are also top-level nodes of the overall data model.
Furthermore, YANG has two mechanisms for contributing a schema hierarchy defined elsewhere to the contents of an internal node of the schema tree; these mechanisms are realized through the following YANG statements:
- The “uses” statement explicitly incorporates the contents of a grouping defined in the same or another module. See Section 4.2.6 of ^RFC7950^ for more details.
- The “augment” statement explicitly adds contents to a target node defined in the same or another module. See Section 4.2.8 of ^RFC7950^ for more details.
With both mechanisms, the source or target YANG module explicitly defines the exact location in the schema tree where the new nodes are placed.
In some cases these mechanisms are not sufficient; it is often necessary that an existing module (or a set of modules) is added to the data model starting at a non-root location. For example, YANG modules such as “ietf-interfaces” ^RFC7223^ are often defined so as to be used in a data model of a physical device. Now suppose we want to model a device that supports multiple logical devices ^I-D.ietf-rtgwg-lne-model^, each of which has its own instantiation of “ietf-interfaces”, and possibly other modules, but, at the same time, we want to be able to manage all these logical devices from the master device. Hence, we would like to have a schema like this:
+–rw interfaces
| +–rw interface* [name] |
| … |
+–rw logical-device* [name] +–rw name
| … |
+–rw interfaces +–rw interface* [name] …
With the “uses” approach, the complete schema tree of “ietf-interfaces” would have to be wrapped in a grouping, and then this grouping would have to be used at the top level (for the master device) and then also in the “logical-device” list (for the logical devices). This approach has several disadvantages:
- It is not scalable because every time there is a new YANG module that needs to be added to the logical device model, we have to update the model for logical devices with another “uses” statement pulling in contents of the new module.
- Absolute references to nodes defined inside a grouping may break if the grouping is used in different locations.
- Nodes defined inside a grouping belong to the namespace of the module where it is used, which makes references to such nodes from other modules difficult or even impossible.
- It would be difficult for vendors to add proprietary modules when the “uses” statements are defined in a standard module.
With the “augment” approach, “ietf-interfaces” would have to augment the “logical-device” list with all its nodes, and at the same time define all its nodes at the top level. The same hierarchy of nodes would thus have to be defined twice, which is clearly not scalable either.
This document introduces a new generic mechanism, denoted as schema mount, that allows for mounting one data model consisting of any number of YANG modules at a specified location of another (parent) schema. Unlike the “uses” and “augment” approaches discussed above, the mounted modules needn’t be specially prepared for mounting and, consequently, existing modules such as “ietf-interfaces” can be mounted without any modifications.
The basic idea of schema mount is to label a data node in the parent schema as the mount point, and then define a complete data model to be attached to the mount point so that the labeled data node effectively becomes the root node of the mounted data model.
In principle, the mounted schema can be specified at three different phases of the data model life cycle:
- Design-time: the mounted schema is defined along with the mount point in the parent YANG module. In this case, the mounted schema has to be the same for every implementation of the parent module.
- Implementation-time: the mounted schema is defined by a server implementor and is as stable as YANG library information, i.e., it may change after an upgrade of server software but not after rebooting the server. Also, a client can learn the entire schema together with YANG library data.
- Run-time: the mounted schema is defined by instance data that is part of the mounted data model. If there are multiple instances of the same mount point (e.g., in multiple entries of a list), the mounted data model may be different for each instance.
The schema mount mechanism defined in this document provides support only for the latter two cases. Design-time mounts are outside the scope of this document, and could be possibly dealt with in a future revision of the YANG data modeling language.
Schema mount applies to the data model, and specifically does not assume anything about the source of instance data for the mounted schemas. It may be implemented using the same instrumentation as the rest of the system, or it may be implemented by querying some other system. Future specifications may define mechanisms to control or monitor the implementation of specific mount points.
This document allows mounting of complete data models only. Other specifications may extend this model by defining additional mechanisms such as mounting sub-hierarchies of a module.
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14, ^RFC2119^.
The following terms are defined in ^RFC6241^ and are not redefined here:
- client
- notification
- server
The following terms are defined in ^RFC7950^ and are not redefined here:
- action
- configuration data
- container
- list
- operation
The following terms are defined in ^RFC7223^ and are not redefined here:
- system-controlled interface
Tree diagrams used in this document follow the notation defined in ^I-D.ietf-netmod-yang-tree-diagrams^.
- inline schema: a mounted schema whose definition is provided as part of the mounted data, using YANG library ^RFC7895^.
- mount point: container or list node whose definition contains the “mount-point” extension statement. The argument of the “mount-point” statement defines the name of the mount point.
- parent schema (of a particular mounted schema): the schema that contains the mount point for the mounted schema.
- top-level schema: a schema according to ^RFC7950^ in which schema trees of each module (except augments) start at the root node.
In this document, names of data nodes, YANG extensions, actions and other data model objects are often used without a prefix, as long as it is clear from the context in which YANG module each name is defined. Otherwise, names are prefixed using the standard prefix associated with the corresponding YANG module, as shown in ^prefixtab^.
– Namespace Prefixes @prefixtab@
| Prefix | YANG module | Reference |
|---|---|---|
| yangmnt | ietf-yang-schema-mount | ^yangmod^ |
| inet | ietf-inet-types | ^RFC6991^ |
| yang | ietf-yang-types | ^RFC6991^ |
| yanglib | ietf-yang-library | ^RFC7895^ |
The schema mount mechanism defined in this document provides a new extensibility mechanism for use with YANG 1.1. In contrast to the existing mechanisms described in ^intro^, schema mount defines the relationship between the source and target YANG modules outside these modules. The procedure consists of two separate steps that are described in the following subsections.
A “container” or “list” node becomes a mount point if the “mount-point” extension (defined in the “ietf-yang-schema-mount” module) is used in its definition. This extension can appear only as a substatement of “container” and “list” statements.
The argument of the “mount-point” extension is a YANG identifier that defines the name of the mount point. A module MAY contain multiple “mount-point” statements having the same argument.
It is therefore up to the designer of the parent schema to decide about the placement of mount points. A mount point can also be made conditional by placing “if-feature” and/or “when” as substatements of the “container” or “list” statement that represents the mount point.
The “mount-point” statement MUST NOT be used in a YANG version 1 module. Note, however, that modules written in any YANG version, including version 1, can be mounted under a mount point.
Mounted schemas for all mount points in the parent schema are determined from state data in the “yangmnt:schema-mounts” container. Data in this container is intended to be as stable as data in the top-level YANG library ^RFC7895^. In particular, it SHOULD NOT change during the same management session.
Generally, the modules that are mounted under a mount point have no relation to the modules in the parent schema; specifically, if a module is mounted it may or may not be present in the parent schema and, if present, its data will generally have no relationship to the data of the parent. Exceptions are possible and such needs to be defined in the model defining the exception, e.g., the interface module in ^I-D.ietf-rtgwg-lne-model^.
The “schema-mounts” container has the “mount-point” list as one of its children. Every entry of this list refers through its key to a mount point and specifies the mounted schema.
If a mount point is defined in the parent schema but does not have an entry in the “mount-point” list, then the mounted schema is void, i.e., instances of that mount point MUST NOT contain any data above those that are defined in the parent schema.
If multiple mount points with the same name are defined in the same module - either directly or because the mount point is defined in a grouping and the grouping is used multiple times - then the corresponding “mount-point” entry applies equally to all such mount points.
The “config” property of mounted schema nodes is overridden and all nodes in the mounted schema are read-only (“config false”) if at least one of the following conditions is satisfied for a mount point:
- the mount point is itself defined as “config false”
- the “config” leaf in the corresponding entry of the “mount-point” list is set to “false”.
An entry of the “mount-point” list can specify the mounted schema in two different ways:
- by stating that the schema is available inline, i.e., in run-time instance data; or
- by referring to one or more entries of the “schema” list in the same instance of “schema-mounts”.
In case 1, the mounted schema is determined at run time: every instance of the mount point that exists in the parent tree MUST contain a copy of YANG library data ^RFC7895^ that defines the mounted schema exactly as for a top-level data model. A client is expected to retrieve this data from the instance tree, possibly after creating the mount point. Instances of the same mount point MAY use different mounted schemas.
In case 2, the mounted schema is defined by the combination of all “schema” entries referred to in the “use-schema” list. In this case, the mounted schema is specified as implementation-time data that can be retrieved together with YANG library data for the parent schema, i.e., even before any instances of the mount point exist. However, the mounted schema has to be the same for all instances of the mount point. Note, that in this case a mount point may include a mounted YANG library module and the data contained in the mounted module MUST exactly match the data contained in the “schema” entries associated with the mount point.
Each entry of the “schema” list contains:
- a list in the YANG library format specifying all YANG modules (and revisions etc.) that are implemented or imported in the mounted schema. Note that this includes modules that solely augment other listed modules;
- (optionally) a new “mount-point” list that applies to mount points defined within the mounted schema.
YANG modules in a mounted schema MAY again contain mount points under which subschemas can be mounted. Consequently, it is possible to construct data models with an arbitrary number of schema levels. A subschema for a mount point contained in a mounted module can be specified in one of the following ways:
- by implementing “ietf-yang-library” and “ietf-yang-schema-mount” modules in the mounted schema, and specifying the subschemas exactly as it is done in the top-level schema
- by using the “mount-point” list inside the corresponding “schema” entry.
The former method is applicable to both “inline” and “use-schema” cases whereas the latter requires the “use-schema” case. On the other hand, the latter method allows for a compact representation of a multi-level schema the does not rely on the presence of any instance data.
A fundamental design principle of schema mount is that the mounted data model works exactly as a top-level data model, i.e., it is confined to the “mount jail”. This means that all paths in the mounted data model (in leafrefs, instance-identifiers, XPath expressions, and target nodes of augments) are interpreted with the mount point as the root node. YANG modules of the mounted schema as well as corresponding instance data thus cannot refer to schema nodes or instance data outside the mount jail.
However, this restriction is sometimes too severe. A typical example is network instances (NI) ^I-D.ietf-rtgwg-ni-model^, where each NI has its own routing engine but the list of interfaces is global and shared by all NIs. If we want to model this organization with the NI schema mounted using schema mount, the overall schema tree would look schematically as follows:
+–rw interfaces
| +–rw interface* [name] |
| … |
+–rw network-instances +–rw network-instance* [name] +–rw name +–rw root +–rw routing …
Here, the “root” node is the mount point for the NI schema. Routing configuration inside an NI often needs to refer to interfaces (at least those that are assigned to the NI), which is impossible unless such a reference can point to a node in the parent schema (interface name).
Therefore, schema mount also allows for such references. For every schema mounted using the “use-schema” method, it is possible to specify a leaf-list named “parent-reference” that contains zero or more XPath 1.0 expressions. Each expression is evaluated with the root of the parent data tree as the context node and the result MUST be a nodeset (see the description of the “parent-reference” node for a complete definition of the evaluation context). For the purposes of evaluating XPath expressions within the mounted data tree, the union of all such nodesets is added to the accessible data tree.
It is worth emphasizing that
- The nodes specified in “parent-reference” leaf-list are available in the mounted schema only for XPath evaluations. In particular, they cannot be accessed there via network management protocols such as NETCONF ^RFC6241^ or RESTCONF ^RFC8040^.
- The mechanism of referencing nodes in the parent schema is not available for schemas mounted using the “inline” method.
If a mounted YANG module defines an RPC operation, clients can invoke this operation by representing it as an action defined for the corresponding mount point, see Section 7.15 of ^RFC7950. An example of this is given in ^invoke-rpc^.
Similarly, if the server emits a notification defined at the top level of any mounted module, it MUST be represented as if the notification was connected to the mount point, see Section 7.16 of ^RFC7950^.
Note, inline actions and notifications will not work when they are contained within a list node without a “key” statement (see section 7.15 and 7.16 of ^RFC7950^). Therefore, to be useful, mount points which contain modules with RPCs, actions, and notifications SHOULD NOT have any ancestor node that is a list node without a “key” statement. This requirement applies to the definition of modules using the “mount-point” extension statement.
Network management of devices that use a data model with schema mount can be implemented in different ways. However, the following implementations options are envisioned as typical:
- shared management: instance data of both parent and mounted schemas are accessible within the same management session.
- split management: one (master) management session has access to instance data of both parent and mounted schemas but, in addition, an extra session exists for every instance of the mount point, having access only to the mounted data tree.
This document defines the YANG 1.1 module ^RFC7950^ “ietf-yang-schema-mount”, which has the following structure:
!! include-figure ietf-yang-schema-mount.tree
This module references ^RFC6991^ and ^RFC7895^.
!! include-figure ietf-yang-schema-mount.yang extract-to=”[email protected]”
This document registers a URI in the IETF XML registry ^RFC3688^. Following the format in RFC 3688, the following registration is requested to be made.
URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
This document registers a YANG module in the YANG Module Names registry ^RFC6020^.
name: ietf-yang-schema-mount namespace: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount prefix: yangmnt reference: RFC XXXX
TBD
The idea of having some way to combine schemas from different YANG modules into one has been proposed independently by several groups of people: Alexander Clemm, Jan Medved, and Eric Voit (^I-D.clemm-netmod-mount^); and Lou Berger and Christian Hopps:
- Lou Berger, LabN Consulting, L.L.C., <[email protected]>
- Alexander Clemm, Huawei, <[email protected]>
- Christian Hopps, Deutsche Telekom, <[email protected]>
- Jan Medved, Cisco, <[email protected]>
- Eric Voit, Cisco, <[email protected]>
*! start-appendix
This non-normative example demonstrates an implementation of the device model as specified in Section 2 of ^I-D.ietf-rtgwg-device-model^, using both logical network elements (LNE) and network instances (NI).
The data model for the physical device may be described by this YANG library content:
!! include-figure yang-library-ex1-device.json
Each LNE can have a specific data model that is determined at run time, so it is appropriate to mount it using the “inline” method, hence the following “schema-mounts” data:
!! include-figure schema-mounts-ex1-device.json
An administrator of the host device has to configure an entry for each LNE instance, for example,
!! include-figure config-ex1-device.json
and then also place necessary state data as the contents of the “root” instance, which should include at least
- YANG library data specifying the LNE’s data model, for example:
!! include-figure yang-library-ex1-lne.json
- state data for interfaces assigned to the LNE instance (that effectively become system-controlled interfaces for the LNE), for example:
!! include-figure interfaces-ex1-lne.json
Assuming that network instances share the same data model, it can be mounted using the “use-schema” method as follows:
!! include-figure schema-mounts-ex1-lne.json
Note also that the “ietf-interfaces” module appears in the “parent-reference” leaf-list for the mounted NI schema. This means that references to LNE interfaces, such as “outgoing-interface” in static routes, are valid despite the fact that “ietf-interfaces” isn’t part of the NI schema.
Assume that the mounted NI data model also implements the “ietf-isis” module ^I-D.ietf-isis-yang-isis-cfg^. An RPC operation defined in this module, such as “clear-adjacency”, can be invoked by a client session of a LNE’s RESTCONF server as an action tied to a the mount point of a particular network instance using a request URI like this (all on one line):
POST restconf/data/ietf-network-instance:network-instances network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1
{{document: name ; ipr trust200902; category std; references back.xml; title “YANG Schema Mount”; abbreviation “YANG Schema Mount”; contributor “author:Martin Bjorklund:Tail-f Systems:[email protected]”; contributor “author:Ladislav Lhotka:CZ.NIC:[email protected]”; }}