YANG Full Embed

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 5 September 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

[RFC8528] introduces the challenges of reusing existing YANG modules, especially when including the full subtree of YANG module 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 [I-D.ietf-opsawg-collected-data-manifest]. In this draft, the goal is to provide a YANG model giving the context in which YANG-push [RFC8641] 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 [RFC8525] and YANG Push [RFC8641] 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 [I-D.havel-opsawg-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 [RFC8528] and Peer Mount [I-D.clemm-netmod-peermount] 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 mounted at that mount point is left to the NETCONF [RFC6241] 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 server (remote or local) with a subtree of the local server. Again, the contents under the local subtree cannot be enforced from the design time.¶

The notion of reusing an existing schema within a new schema is not new. Several schema definition languages propose this feature, such as RELAX NG, Protobuf or json-schema.¶

In this document, we propose a new extension, named full embed. This extension enables reusing imported modules by rooting them at an arbitrary point of the data model. The concept of mount point from [RFC8528] is replaced by an anydata statement containing list of "full:embed" 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 embed rather than mount. Also, we use 'embed' not to conflict with the native 'include' statement in YANG [RFC7950].¶

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.¶

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

The following terms are defined in [RFC7950]:¶

• data model¶
• data node¶

The following terms are defined in [RFC8528]:¶

• mount point¶

3. Full Embed

The full embed mechanism defined in this document completes [RFC8528], 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 [RFC8528].¶

The approach for supporting the full embed mechanism is to keep the semantics of [RFC8528] for the resulting data model. In [RFC8528], the list of modules to mount in each mount point is left to the NETCONF server. In this document, we propose the full embed mechanism to define this mapping directly in the YANG module that embeds the mounted modules.¶

To ensure interoperability with clients that do not support the full embed extension, the full embed statement can only appear within an anydata node. Clients that do not support the extension will see the contents of the embedded model as arbitrary data. Clients that support the extension will be able to interpret the contents of the anydata node according to the semantics of the embedded YANG modules.¶

In the sequel, we use "full" as the prefix for the module 'ietf-yang-full-embed' (see Section 4). Thus "full:embed" refers to the extension 'embed' defined in that module.¶

4. ietf-full-embed YANG module

We present in this section the YANG module defining the "full-embed" extension. The module in itself defines solely the 'embed' extension. A module importing this extension SHOULD use the prefix 'full', so that the statement reads "full:embed" when used in the code.¶

<CODE BEGINS> file "ietf-full-embed@2023-11-03.yang"

module ietf-yang-full-embed {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-yang-full-embed";
  prefix full;

  organization
    "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
  contact
    "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
     WG List:  <mailto:netmod@ietf.org>

     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 Embed";
  }

  extension embed {
    argument prefix;
    description
      "The argument 'prefix' MUST be the prefix of a module imported
       by the calling module.

       The 'embed' statement MUST NOT be used in a YANG version 1
       module, neither explicitly nor via a 'uses' statement.

       The 'embed' statement MAY be present as a substatement of
       'anydata' and MUST NOT be present elsewhere.

       Whenever a sequence of 'embed' 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";
  }
}


<CODE ENDS>

5. Security Considerations

TODO¶

6. IANA Considerations

TODO¶

Appendix B. Examples

In this section we present some minimalistic examples in order to illustrate the "full:embed" 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 ([RFC8340]) of the 'device-level' module is depicted in Figure 2.¶

module: device-level
  +--rw hostname     string
  +--ro cpu-usage?   int8

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

module: network-level-stub
  +--rw devices
     +--rw device* [device-id]
        +--rw device-id    string

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

module network-level {
  yang-version 1.1;
  namespace "urn:network-level";
  prefix "net-l";

  import "ietf-yang-full-include" {
    prefix "full";
  }

  import "device-level" {
    prefix "dev-l";
  }

  container devices {
    list device {
      key device-id;
      leaf device-id {
        type string;
      }
      anydata device-content {
           full:include "dev-l";
      }
    }
  }
}

module network-level {
  yang-version 1.1;
  namespace "urn:network-level";
  prefix "net-l";

  import ietf-yang-schema-mount {
    prefix yangmnt;
  }

  container devices {
    list device {
      key device-id;
      leaf device-id {
        type string;
      }
      container device-contents{
        yangmnt:mount-point "device-schema";
      }
    }
  }
}

module: network-level
  +--rw devices
     +--rw device* [device-id]
        +--rw device-id          string
        +--mp device-contents
           +--rw hostname/    string
           +--ro cpu-usage/?  int8

module device-level {
  yang-version 1.1;
  namespace "urn:device-level";
  prefix mnt;

  leaf hostname {
    type string;
    mandatory true;
  }
  leaf cpu-usage {
    type int8;
    config false;
  }
}

<CODE BEGINS> file "network-level-yanglib.xml"

<yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"
     xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
   <module-set>
     <name>main-set</name>
     <module>
       <name>ietf-datastores</name>
       <revision>2018-02-14</revision>
       <namespace>
           urn:ietf:params:xml:ns:yang:ietf-datastores
       </namespace>
     </module>
     <module>
       <name>ietf-yang-library</name>
       <revision>2019-01-04</revision>
       <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-library
       </namespace>
     </module>
     <module>
       <name>ietf-yang-schema-mount</name>
       <revision>2019-01-14</revision>
       <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
       </namespace>
     </module>
     <module>
       <name>network-level</name>
       <namespace>urn:network-level</namespace>
     </module>
     <import-only-module>
       <name>ietf-yang-types</name>
       <revision>2013-07-15</revision>
       <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-types
       </namespace>
     </import-only-module>
     <import-only-module>
       <name>ietf-inet-types</name>
       <revision>2013-07-15</revision>
       <namespace>
           urn:ietf:params:xml:ns:yang:ietf-inet-types
       </namespace>
     </import-only-module>
   </module-set>
   <schema>
     <name>main-schema</name>
     <module-set>main-set</module-set>
   </schema>
   <datastore>
     <name>ds:running</name>
     <schema>main-schema</schema>
   </datastore>
   <datastore>
     <name>ds:operational</name>
     <schema>main-schema</schema>
   </datastore>
   <content-id>1</content-id>
 </yang-library>
 <modules-state
   xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
   <module-set-id>2</module-set-id>
 </modules-state>


<CODE ENDS>

<CODE BEGINS> file "extension_data.xml"

<yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"
             xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
    <module-set>
        <name>mountee-set</name>
        <module>
            <name>device-level</name>
            <namespace>urn:device-level</namespace>
        </module>
        <module>
            <name>ietf-datastores</name>
            <revision>2018-02-14</revision>
            <namespace>
                urn:ietf:params:xml:ns:yang:ietf-datastores
            </namespace>
        </module>
        <module>
            <name>ietf-yang-library</name>
            <revision>2019-01-04</revision>
            <namespace>
                urn:ietf:params:xml:ns:yang:ietf-yang-library
            </namespace>
        </module>
        <import-only-module>
            <name>ietf-yang-types</name>
            <revision>2013-07-15</revision>
            <namespace>
                urn:ietf:params:xml:ns:yang:ietf-yang-types
            </namespace>
        </import-only-module>
        <import-only-module>
            <name>ietf-inet-types</name>
            <revision>2013-07-15</revision>
            <namespace>
                urn:ietf:params:xml:ns:yang:ietf-inet-types
            </namespace>
        </import-only-module>
    </module-set>
    <schema>
        <name>test-schema</name>
        <module-set>mountee-set</module-set>
    </schema>
    <datastore>
        <name>ds:running</name>
        <schema>test-schema</schema>
    </datastore>
    <datastore>
        <name>ds:operational</name>
        <schema>test-schema</schema>
    </datastore>
    <content-id>2</content-id>
</yang-library>
<modules-state
    xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
    <module-set-id>2</module-set-id>
</modules-state>
<schema-mounts
    xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount">
    <mount-point>
        <module>network-level</module>
        <label>device-schema</label>
        <shared-schema/>
    </mount-point>
</schema-mounts>


<CODE ENDS>

Authors' Addresses