]> Huawei

thomas.joubert1@huawei-partners.com

Huawei

jean.quilbeuf@huawei.com

Huawei

benoit.claise@huawei.com

General NETMOD YANG lacks re-usability of models defined outside of the grouping and augmentation mechanisms. For instance, it is almost impossible to reuse a model defined for a device in the context of the network, i.e by encapsulating it in a list indexed by device IDs. defines the YANG mount mechanism, partially solving the problem by allowing to include schemas at deploy or runtime. This document aims to provide the same mechanism at design time.

Introduction introduces the challenges of reusing existing YANG modules, especially when they need to be included under a specific node of another module. In that RFC, three different phases of data model life cycle are identified: "design time", "implementation time" and "run time". Only the last two are covered. We focus here on the first phase of the life cycle, that is inserting modules at design time. We identified some use cases that require this design time definition of which modules need to be included in the top-level module. The have in common the need to re-use YANG modules defined for the devices in the context of a network-level module. Also, they both aim to define a model that is independent of the underlying devices.

• The use case that triggered the creation of this document is . In this draft, the goal is to provide a YANG model giving the context in which YANG-push data are collected so that they can be exploited a posteriori. To get the full context, we need the hardware and os version of each device, but also the list of YANG modules supported by the devices and the parameters for the YANG-push subscriptions. For the last two items YANG Library and YANG Push provide good and standard modules for representing this information at the device level. However, the data manifests need to be considered at the network level, so that we can distinguish between the devices from which they come. In YANG, that means including them in a list indexed by the device id, which proves out to be difficult without copy-pasting the original modules.
• A similar use case is the digital map , where the goal is to build a model of the network. In particular, to model the devices a lot of standard modules have already been defined by the IETF and there is a need to reuse these modules to build this larger network model. The IVY workgroup might also rely on the pattern of re-using device level modules into a network model.

YANG Schema Mount and Peer Mount focus on mounting a given part of a an existing data instance into another data instance. Although the final goal is the same: being able to reuse modules defined elsewhere in order to avoid redefining them, the approach is more focused on the runtime than the design time. In the first case, the mapping between the mount points and the existing modules to be included at that mount point is left to the NETCONF server. Thus, to guarantee that the contents under a given mount point conforms to a predefined schema requires the proper configuration of the server. In the case of Peer mount, the focus is on synchronizing a given subtree of a remote server with a subtree of the local server. Again, the contents under the local subtree cannot be enforced from the design time. In this document, we propose a new extension, named full include. This extension enables reusing imported modules by rooting them at an arbitrary point of the data model. The concept of mount point from is replaced by a list of "full:include" statement, each statement corresponding to the inclusion of one imported module at that location. In that sense, the design time solution is a pure YANG solution that does not rely on external configuration to specify the list of mounted modules, hence the term full include rather than mount. The obtained data model that we want to associate to our construct is similar to the one obtained by specifying a mount point and binding it to the same set of modules. Therefore, we can reuse the concepts of the YANG schema mount to define the semantics of our new extension.

Terminology The key words "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 when, and only when, they appear in all capitals, as shown here. The following terms are defined in :

• data model
• data node

The following terms are defined in :

• mount point

Full Include The full include mechanism defined in this document completes , by providing a mechanism to "mount" modules at design time. Supporting mounting modules at this step of the data model life cycle is left out of scope in . The approach for supporting the full include mechanism is to keep the semantics of for the resulting data model. In , the list of modules to mount in each mount point is left to the NETCONF server. In this document, we propose the full include mechanism to define this mapping directly in the YANG module that includes the mounted modules. In the sequel, we use "full" as the prefix for the module 'ietf-yang-full-include' (see ). Thus "full:include" refers to the extension 'include' defined in that module.

Definition The "full:include" statement can appear as a sub-statement of the following statements:

• container
• list

The "full:include" statement takes as an argument a prefix, that must be the prefix associated to an imported module. Modules can contain multiple uses of the "full:include" statement. The "container" and "list" statements MAY contain multiple uses of the "full:include" statement on the same level. These multiple uses define the full list of modules to be included, rooted in node where the "full:include" statement is used. The "full:include" statement can be interpreted using YANG Schema Mount , by following these steps:

1. For each set of "full:include" statement located in the same node, replace them by a single "mount-point" with a unique label.
2. Declare each of these "mount-points" as "shared-schema" in the data model defined in .
3. In the instance corresponding to each "mount-point", define the ietf-yang-library to include a module-set (at '/yang-library/module-set/) with the following. The list 'module' contains an entry for every module referred to in the set of "full:include" statements corresponding to the "mount-point". Additionally, the list 'module' contains an entry for "ietf-yang-library" as it is needed by YANG Schema mount. As usual, the list 'imported-modules' contains the list of dependencies needed by the modules in the 'module' list.

An example of module using "full:include" and its translation into a similar YANG Schema mount version is presented in .

Limitations

• A module MUST NOT use the "full:include" statement with its own prefix as argument. This rule prevents any infinite recursion in the mounted schemas.
• Modules used as arguments for the "full:include" statement MUST be valid and compile successfully, independently of the module it is used in.

ietf-full-include YANG module We present in this section the YANG module defining the "full-include" extension. The module in itself defines solely the 'include' extension. A module importing this extension SHOULD the prefix 'full', so that the statement reads "full:include" when used in the code. WG List: Editor: "; description "This module defines a YANG extension statement that can be used to incorporate data models defined in other YANG modules in a module. The key words '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 (RFC 2119) (RFC 8174) when, and only when, they appear in all capitals, as shown here. Copyright (c) 2023 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Revised BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; revision 2023-11-05 { description "Initial revision."; reference "RFC XXXX: YANG Full Include"; } extension include { argument prefix; description "The argument 'prefix' MUST be the prefix of a module imported by the calling module. The 'include' statement MUST NOT be used in a YANG version 1 module, neither explicitly nor via a 'uses' statement. The 'include' statement MAY be present as a substatement of 'container' and 'list' and MUST NOT be present elsewhere. Whenever a sequence of 'include' statements is used, the schema tree defined by the set of the included modules is inserted in the schema tree of the calling module, at the place where the sequence is declared"; } } ]]>

Security Considerations TODO

IANA Considerations TODO

Contributors

Open issues

• What name should we give to this draft? Any suggestions instead of full include?
• Do we want to support the parent-nodes mechanism from ?
• Do we allow full include from within a grouping?
• Does this mechanism already exist?

References Normative References Informative References

Changes between revisions No revisions

Examples In this section we present some minimalistic examples in order to illustrate the "full:include" statement. For these examples, we are in a situation where we have a device-level module already defined and we want to have a network-level module that represent a list of device, each having an independent instance of the device-level module. This situation might arise if we want to simplify the network management by presenting a unified model for the network. In that case, the heterogeneity of the devices should be handled by mapping their model to the device-level module (which is clearly out of scope for this draft). In our simplistic example, the device-level module simply exposes the hostname and the cpu-usage of the device. Note that we cannot modify this device-level module, because in a more realistic example we would be reusing standard modules. The tree representation () of the 'device-level' module is depicted in .

YANG Tree representation of the device-level module.

For the network-level module, we have a list of devices indexed by their 'device-id'. The tree representation () of such a module is depicted in .

YANG Tree representation of a stub for the network-level module

The goal is now to complete this stub so that the full contents of the 'device-level' is added under the "device" list.

Example using YANG Full Include We propose in this section a YANG module for 'network-level'. The YANG code is presented in .

Version of the network-level module using full:include

At the moment, this code is accepted by the YANG compilers, but since the extension is not implemented, it simply ignores it. Note that all the information (which modules to include, where to include them) is defined in this module. More specifically, the line 'full:include "dev-l";' states that the full schema of the 'device-level' module, identified by its prefix "dev-l" must be included at that location. By adding more occurrences of "full:include" there, one can define a more complex schema to be included at that location.

Using YANG Schema Mount In this section, we show how a similar result could be attained using YANG Schema Mount. The network-level module is presented in .

Version of the network-level module using Schema Mount

As explained in , the yang-library corresponding to the modules to include, as well as the data required by 'ietf-yang-mount' needs to be specified in some other files. Using the 'yanglint' tool from libyang (), this module can be compiled to provide a tree representation as shown in .

Full tree of both network- and device-level using Schema Mount

The command for obtaining that schema is 'yanglint -f tree -p . -x extension-data.xml -Y network-level-yanglib.xml yang/network-level.yang', assuming all the YANG modules and the two xml files are in the current folder. The file 'network-level-yanglib.xml' contains the YANG Library data for the network-level module. The file 'extension-data.xml' contains the YANG Library data defining the schema to use at the mount point, as well as the data required by YANG Schema Mount. Both are reproduced in .

Support Files The code of the 'device-level' module is given in . Then the data files 'network-level-yanglib.xml' and 'extension_data.xml' are provided. These files are needed to compile the Schema Mount version of our example with yanglint.

device-level YANG module

main-set ietf-datastores 2018-02-14 urn:ietf:params:xml:ns:yang:ietf-datastores ietf-yang-library 2019-01-04 urn:ietf:params:xml:ns:yang:ietf-yang-library ietf-yang-schema-mount 2019-01-14 urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount network-level urn:network-level ietf-yang-types 2013-07-15 urn:ietf:params:xml:ns:yang:ietf-yang-types ietf-inet-types 2013-07-15 urn:ietf:params:xml:ns:yang:ietf-inet-types main-schema main-set ds:running main-schema ds:operational main-schema 1 2 ]]> mountee-set device-level urn:device-level ietf-datastores 2018-02-14 urn:ietf:params:xml:ns:yang:ietf-datastores ietf-yang-library 2019-01-04 urn:ietf:params:xml:ns:yang:ietf-yang-library ietf-yang-types 2013-07-15 urn:ietf:params:xml:ns:yang:ietf-yang-types ietf-inet-types 2013-07-15 urn:ietf:params:xml:ns:yang:ietf-inet-types test-schema mountee-set ds:running test-schema ds:operational test-schema 2 2 network-level device-schema ]]>

Acknowledgements TODO: acknowledgements