Tech-invite   World Map
3GPPspecs     Glossaries     IETF     RFCs     Groups     SIP     ABNFs

RFC 8345

Proposed STD
Pages: 57
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: I2RS

A YANG Data Model for Network Topologies

Part 1 of 3, p. 1 to 19
None       Next Section


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                          A. Clemm
Request for Comments: 8345                                        Huawei
Category: Standards Track                                      J. Medved
ISSN: 2070-1721                                                    Cisco
                                                                R. Varga
                                               Pantheon Technologies SRO
                                                              N. Bahadur
                                                       Bracket Computing
                                                      H. Ananthakrishnan
                                                           Packet Design
                                                                  X. Liu
                                                              March 2018

                A YANG Data Model for Network Topologies


   This document defines an abstract (generic, or base) YANG data model
   for network/service topologies and inventories.  The data model
   serves as a base model that is augmented with technology-specific
   details in other, more specific topology and inventory data models.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at

Top      ToC       Page 2 
Copyright Notice

   Copyright (c) 2018 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
   ( 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 Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Top       Page 3 
Table of Contents

   1. Introduction ....................................................4
   2. Key Words .......................................................8
   3. Definitions and Abbreviations ...................................9
   4. Model Structure Details .........................................9
      4.1. Base Network Model .........................................9
      4.2. Base Network Topology Data Model ..........................12
      4.3. Extending the Data Model ..................................13
      4.4. Discussion and Selected Design Decisions ..................14
           4.4.1. Container Structure ................................14
           4.4.2. Underlay Hierarchies and Mappings ..................14
           4.4.3. Dealing with Changes in Underlay Networks ..........15
           4.4.4. Use of Groupings ...................................15
           4.4.5. Cardinality and Directionality of Links ............16
           4.4.6. Multihoming and Link Aggregation ...................16
           4.4.7. Mapping Redundancy .................................16
           4.4.8. Typing .............................................17
           4.4.9. Representing the Same Device in Multiple Networks ..17
           4.4.10. Supporting Client-Configured and
                   System-Controlled Network Topologies ..............18
           4.4.11. Identifiers of String or URI Type .................19
   5. Interactions with Other YANG Modules ...........................19
   6. YANG Modules ...................................................20
      6.1. Defining the Abstract Network: ietf-network ...............20
      6.2. Creating Abstract Network Topology:
           ietf-network-topology .....................................25
   7. IANA Considerations ............................................32
   8. Security Considerations ........................................33
   9. References .....................................................35
      9.1. Normative References ......................................35
      9.2. Informative References ....................................36
   Appendix A. Model Use Cases .......................................38
     A.1. Fetching Topology from a Network Element ...................38
     A.2. Modifying TE Topology Imported from an Optical Controller ..38
     A.3. Annotating Topology for Local Computation ..................39
     A.4. SDN Controller-Based Configuration of Overlays on Top of
          Underlays ..................................................39
   Appendix B. Companion YANG Data Models for Implementations Not
               Compliant with NMDA ...................................39
     B.1. YANG Module for Network State ..............................40
     B.2. YANG Module for Network Topology State .....................45
   Appendix C. An Example ............................................52
   Acknowledgments ...................................................56
   Contributors ......................................................56
   Authors' Addresses ................................................57

Top      ToC       Page 4 
1.  Introduction

   This document introduces an abstract (base) YANG [RFC7950] data model
   [RFC3444] to represent networks and topologies.  The data model is
   divided into two parts: The first part of the data model defines a
   network data model that enables the definition of network
   hierarchies, or network stacks (i.e., networks that are layered on
   top of each other) and maintenance of an inventory of nodes contained
   in a network.  The second part of the data model augments the basic
   network data model with information to describe topology information.
   Specifically, it adds the concepts of "links" and
   "termination points" to describe how nodes in a network are connected
   to each other.  Moreover, the data model introduces vertical layering
   relationships between networks that can be augmented to cover both
   network inventories and network/service topologies.

   Although it would be possible to combine both parts into a single
   data model, the separation facilitates integration of network
   topology and network inventory data models, because it allows network
   inventory information to be augmented separately, and without concern
   for topology, into the network data model.

   The data model can be augmented to describe the specifics of
   particular types of networks and topologies.  For example, an
   augmenting data model can provide network node information with
   attributes that are specific to a particular network type.  Examples
   of augmenting models include data models for Layer 2 network
   topologies; Layer 3 network topologies such as unicast IGP, IS-IS
   [RFC1195], and OSPF [RFC2328]; traffic engineering (TE) data
   [RFC3209]; or any of the variety of transport and service topologies.
   Information specific to particular network types will be captured in
   separate, technology-specific data models.

   The basic data models introduced in this document are generic in
   nature and can be applied to many network and service topologies and
   inventories.  The data models allow applications to operate on an
   inventory or topology of any network at a generic level, where the
   specifics of particular inventory/topology types are not required.
   At the same time, where data specific to a network type comes into
   play and the data model is augmented, the instantiated data still
   adheres to the same structure and is represented in a consistent
   fashion.  This also facilitates the representation of network
   hierarchies and dependencies between different network components and
   network types.

   The abstract (base) network YANG module introduced in this document,
   entitled "ietf-network" (Section 6.1), contains a list of abstract
   network nodes and defines the concept of "network hierarchy" (network

Top      ToC       Page 5 
   stack).  The abstract network node can be augmented in inventory and
   topology data models with inventory-specific and topology-specific
   attributes.  The network hierarchy (stack) allows any given network
   to have one or more "supporting networks".  The relationship between
   the base network data model, the inventory data models, and the
   topology data models is shown in Figure 1 (dotted lines in the figure
   denote possible augmentations to models defined in this document).

                         |                        |
                         | Abstract Network Model |
                         |                        |
                              |               |
                              V               V
                       +------------+  ..............
                       |  Abstract  |  : Inventory  :
                       |  Topology  |  :  Model(s)  :
                       |   Model    |  :            :
                       +------------+  ''''''''''''''
                |             |             |             |
                V             V             V             V
          ............  ............  ............  ............
          :    L1    :  :    L2    :  :    L3    :  :  Service :
          : Topology :  : Topology :  : Topology :  : Topology :
          :   Model  :  :   Model  :  :   Model  :  :   Model  :
          ''''''''''''  ''''''''''''  ''''''''''''  ''''''''''''

                Figure 1: The Network Data Model Structure

   The network-topology YANG module introduced in this document,
   entitled "ietf-network-topology" (Section 6.2), defines a generic
   topology data model at its most general level of abstraction.  The
   module defines a topology graph and components from which it is
   composed: nodes, edges, and termination points.  Nodes (from the
   "ietf-network" module) represent graph vertices and links represent
   graph edges.  Nodes also contain termination points that anchor the
   links.  A network can contain multiple topologies -- for example,
   topologies at different layers and overlay topologies.  The data
   model therefore allows relationships between topologies, as well as
   dependencies between nodes and termination points across topologies,
   to be captured.  An example of a topology stack is shown in Figure 2.

Top      ToC       Page 6 
                   /            _[X1]_          "Service"  /
                  /           _/  :   \_                  /
                 /          _/     :    \_               /
                /         _/        :     \_            /
               /         /           :      \          /
              /       [X2]__________________[X3]      /
                        :              :     :
                   /      :              :   :        "L3" /
                  /        :              :  :            /
                 /         :               : :           /
                /         [Y1]_____________[Y2]         /
               /           *               * *         /
              /            *              *  *        /
                             *           *   *
                   /     [Z1]_______________[Z2] "Optical" /
                  /         \_         *   _/             /
                 /            \_      *  _/              /
                /               \_   * _/               /
               /                  \ * /                /
              /                    [Z]                /

               Figure 2: Topology Hierarchy (Stack) Example

   Figure 2 shows three topology levels.  At the top, the "Service"
   topology shows relationships between service entities, such as
   service functions in a service chain.  The "L3" topology shows
   network elements at Layer 3 (IP), and the "Optical" topology shows
   network elements at Layer 1.  Service functions in the "Service"
   topology are mapped onto network elements in the "L3" topology, which
   in turn are mapped onto network elements in the "Optical" topology.
   Two service functions (X1 and X3) are mapped onto a single L3 network
   element (Y2); this could happen, for example, if two service
   functions reside in the same Virtual Machine (VM) (or server) and
   share the same set of network interfaces.  A single "L3" network
   element (Y2) is mapped onto two "Optical" network elements (Z2 and
   Z).  This could happen, for example, if a single IP router attaches
   to multiple Reconfigurable Optical Add/Drop Multiplexers (ROADMs) in
   the optical domain.

Top      ToC       Page 7 
   Another example of a service topology stack is shown in Figure 3.

                                 VPN1                       VPN2
               +---------------------+    +---------------------+
              /   [Y5]...           /    / [Z5]______[Z3]      /
             /    /  \  :          /    /  : \_       / :     /
            /    /    \  :        /    /   :   \_    /  :    /
           /    /      \  :      /    /   :      \  /   :   /
          /   [Y4]____[Y1] :    /    /   :       [Z2]   :  /
         +------:-------:---:--+    +---:---------:-----:-+
                :        :   :         :          :     :
                :         :   :       :           :     :
                :  +-------:---:-----:------------:-----:-----+
                : /       [X1]__:___:___________[X2]   :     /
                :/         / \_  : :       _____/ /   :     /
                :         /    \_ :  _____/      /   :     /
               /:        /       \: /           /   :     /
              / :       /        [X5]          /   :     /
             /   :     /       __/ \__        /   :     /
            /     :   /    ___/       \__    /   :     /
           /       : / ___/              \  /   :     /
          /        [X4]__________________[X3]..:     /
                                        L3 Topology

               Figure 3: Topology Hierarchy (Stack) Example

   Figure 3 shows two VPN service topologies (VPN1 and VPN2)
   instantiated over a common L3 topology.  Each VPN service topology is
   mapped onto a subset of nodes from the common L3 topology.

   There are multiple applications for such a data model.  For example,
   within the context of Interface to the Routing System (I2RS), nodes
   within the network can use the data model to capture their
   understanding of the overall network topology and expose it to a
   network controller.  A network controller can then use the
   instantiated topology data to compare and reconcile its own view of
   the network topology with that of the network elements that it
   controls.  Alternatively, nodes within the network could propagate
   this understanding to compare and reconcile this understanding either
   among themselves or with the help of a controller.  Beyond the
   network element and the immediate context of I2RS itself, a network
   controller might even use the data model to represent its view of the
   topology that it controls and expose it to applications north of
   itself.  Further use cases where the data model can be applied are
   described in [USECASE-REQS].

Top      ToC       Page 8 
   In this data model, a network is categorized as either system
   controlled or not.  If a network is system controlled, then it is
   automatically populated by the server and represents dynamically
   learned information that can be read from the operational state
   datastore.  The data model can also be used to create or modify
   network topologies that might be associated with an inventory model
   or with an overlay network.  Such a network is not system controlled;
   rather, it is configured by a client.

   The data model allows a network to refer to a supporting network,
   supporting nodes, supporting links, etc.  The data model also allows
   the layering of a network that is configured on top of a network that
   is system controlled.  This permits the configuration of overlay
   networks on top of networks that are discovered.  Specifically, this
   data model is structured to support being implemented as part of the
   ephemeral datastore [RFC8342], the requirements for which are defined
   in Section 3 of [RFC8242].  This allows network topology data that is
   written, i.e., configured by a client and not system controlled, to
   refer to dynamically learned data that is controlled by the system,
   not configured by a client.  A simple use case might involve creating
   an overlay network that is supported by the dynamically discovered
   IP-routed network topology.  When an implementation places written
   data for this data model in the ephemeral datastore, such a network
   MAY refer to another network that is system controlled.

2.  Key Words

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "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.

Top      ToC       Page 9 
3.  Definitions and Abbreviations

   Datastore:  A conceptual place to store and access information.  A
      datastore might be implemented, for example, using files, a
      database, flash memory locations, or combinations thereof.  A
      datastore maps to an instantiated YANG data tree (definition from

   Data subtree:  An instantiated data node and the data nodes that are
      hierarchically contained within it.

   IGP:  Interior Gateway Protocol.

   IS-IS:  Intermediate System to Intermediate System.

   OSPF:  Open Shortest Path First (a link-state routing protocol).

   SDN:  Software-Defined Networking.

   URI:  Uniform Resource Identifier.

   VM:  Virtual Machine.

4.  Model Structure Details

4.1.  Base Network Model

   The abstract (base) network data model is defined in the
   "ietf-network" module.  Its structure is shown in Figure 4.  The
   notation syntax follows the syntax used in [RFC8340].

   module: ietf-network
     +--rw networks
        +--rw network* [network-id]
           +--rw network-id            network-id
           +--rw network-types
           +--rw supporting-network* [network-ref]
           |  +--rw network-ref    -> /networks/network/network-id
           +--rw node* [node-id]
              +--rw node-id            node-id
              +--rw supporting-node* [network-ref node-ref]
                 +--rw network-ref
                 |       -> ../../../supporting-network/network-ref
                 +--rw node-ref       -> /networks/network/node/node-id

     Figure 4: The Structure of the Abstract (Base) Network Data Model

Top      ToC       Page 10 
   The data model contains a container with a list of networks.  Each
   network is captured in its own list entry, distinguished via a

   A network has a certain type, such as L2, L3, OSPF, or IS-IS.  A
   network can even have multiple types simultaneously.  The type or
   types are captured underneath the container "network-types".  In this
   model, it serves merely as an augmentation target; network-specific
   modules will later introduce new data nodes to represent new network
   types below this target, i.e., will insert them below "network-types"
   via YANG augmentation.

   When a network is of a certain type, it will contain a corresponding
   data node.  Network types SHOULD always be represented using presence
   containers, not leafs of type "empty".  This allows the
   representation of hierarchies of network subtypes within the instance
   information.  For example, an instance of an OSPF network (which, at
   the same time, is a Layer 3 unicast IGP network) would contain
   underneath "network-types" another presence container
   "l3-unicast-igp-network", which in turn would contain a presence
   container "ospf-network".  Actual examples of this pattern can be
   found in [RFC8346].

   A network can in turn be part of a hierarchy of networks, building on
   top of other networks.  Any such networks are captured in the list
   "supporting-network".  A supporting network is, in effect, an
   underlay network.

   Furthermore, a network contains an inventory of nodes that are part
   of the network.  The nodes of a network are captured in their own
   list.  Each node is identified relative to its containing network by
   a node-id.

   It should be noted that a node does not exist independently of a
   network; instead, it is a part of the network that contains it.  In
   cases where the same device or entity takes part in multiple
   networks, or at multiple layers of a networking stack, the same
   device or entity will be represented by multiple nodes, one for each
   network.  In other words, the node represents an abstraction of the
   device for the particular network of which it is a part.  To indicate
   that the same entity or device is part of multiple topologies or
   networks, it is possible to create one "physical" network with a list
   of nodes for each of the devices or entities.  This (physical)
   network -- the nodes (entities) in that network -- can then be
   referred to as an underlay network and as nodes from the other
   (logical) networks and nodes, respectively.  Note that the data model

Top      ToC       Page 11 
   allows for the definition of more than one underlay network (and
   node), allowing for simultaneous representation of layered network
   topologies and service topologies, and their physical instantiation.

   Similar to a network, a node can be supported by other nodes and map
   onto one or more other nodes in an underlay network.  This is
   captured in the list "supporting-node".  The resulting hierarchy of
   nodes also allows for the representation of device stacks, where a
   node at one level is supported by a set of nodes at an underlying
   level.  For example:

   o  a "router" node might be supported by a node representing a route
      processor and separate nodes for various line cards and service

   o  a virtual router might be supported or hosted on a physical device
      represented by a separate node,

   and so on.

   Network data of a network at a particular layer can come into being
   in one of two ways: (1) the network data is configured by client
   applications -- for example, in the case of overlay networks that are
   configured by an SDN Controller application, or (2) the network data
   is automatically controlled by the system, in the case of networks
   that can be discovered.  It is possible for a configured (overlay)
   network to refer to a (discovered) underlay network.

   The revised datastore architecture [RFC8342] is used to account for
   those possibilities.  Specifically, for each network, the origin of
   its data is indicated per the "origin" metadata [RFC7952] annotation
   (as defined in [RFC8342]) -- "intended" for data that was configured
   by a client application and "learned" for data that is discovered.
   Network data that is discovered is automatically populated as part of
   the operational state datastore.  Network data that is configured is
   part of the configuration and intended datastores, respectively.
   Configured network data that is actually in effect is, in addition,
   reflected in the operational state datastore.  Data in the
   operational state datastore will always have complete referential
   integrity.  Should a configured data item (such as a node) have a
   dangling reference that refers to a non-existing data item (such as a
   supporting node), the configured data item will automatically be
   removed from the operational state datastore and thus only appear in
   the intended datastore.  It will be up to the client application
   (such as an SDN Controller) to resolve the situation and ensure that
   the reference to the supporting resources is configured properly.

Top      ToC       Page 12 
4.2.  Base Network Topology Data Model

   The abstract (base) network topology data model is defined in the
   "ietf-network-topology" module.  It builds on the network data model
   defined in the "ietf-network" module, augmenting it with links
   (defining how nodes are connected) and termination points (which
   anchor the links and are contained in nodes).  The structure of the
   network topology module is shown in Figure 5.  The notation syntax
   follows the syntax used in [RFC8340].

   module: ietf-network-topology
     augment /nw:networks/nw:network:
       +--rw link* [link-id]
          +--rw link-id            link-id
          +--rw source
          |  +--rw source-node?   -> ../../../nw:node/node-id
          |  +--rw source-tp?     leafref
          +--rw destination
          |  +--rw dest-node?   -> ../../../nw:node/node-id
          |  +--rw dest-tp?     leafref
          +--rw supporting-link* [network-ref link-ref]
             +--rw network-ref
             |       -> ../../../nw:supporting-network/network-ref
             +--rw link-ref       leafref
     augment /nw:networks/nw:network/nw:node:
       +--rw termination-point* [tp-id]
          +--rw tp-id                           tp-id
          +--rw supporting-termination-point*
                  [network-ref node-ref tp-ref]
             +--rw network-ref
             |       -> ../../../nw:supporting-node/network-ref
             +--rw node-ref
             |       -> ../../../nw:supporting-node/node-ref
             +--rw tp-ref         leafref

      Figure 5: The Structure of the Abstract (Base) Network Topology
                                Data Model

   A node has a list of termination points that are used to terminate
   links.  An example of a termination point might be a physical or
   logical port or, more generally, an interface.

   Like a node, a termination point can in turn be supported by an
   underlying termination point, contained in the supporting node of the
   underlay network.

Top      ToC       Page 13 
   A link is identified by a link-id that uniquely identifies the link
   within a given topology.  Links are point-to-point and
   unidirectional.  Accordingly, a link contains a source and a
   destination.  Both source and destination reference a corresponding
   node, as well as a termination point on that node.  Similar to a
   node, a link can map onto one or more links (which are terminated by
   the corresponding underlay termination points) in an underlay
   topology.  This is captured in the list "supporting-link".

4.3.  Extending the Data Model

   In order to derive a data model for a specific type of network, the
   base data model can be extended.  This can be done roughly as
   follows: a new YANG module for the new network type is introduced.
   In this module, a number of augmentations are defined against the
   "ietf-network" and "ietf-network-topology" modules.

   We start with augmentations against the "ietf-network" module.
   First, a new network type needs to be defined; this is done by
   defining a presence container that represents the new network type.
   The new network type is inserted, by means of augmentation, below the
   network-types container.  Subsequently, data nodes for any node
   parameters that are specific to a network type are defined and
   augmented into the node list.  The new data nodes can be defined as
   conditional ("when") on the presence of the corresponding network
   type in the containing network.  In cases where there are any
   requirements or restrictions in terms of network hierarchies, such as
   when a network of a new network type requires a specific type of
   underlay network, it is possible to define corresponding constraints
   as well and augment the supporting-network list accordingly.
   However, care should be taken to avoid excessive definitions of

   Subsequently, augmentations are defined against the
   "ietf-network-topology" module.  Data nodes are defined for link
   parameters, as well as termination point parameters, that are
   specific to the new network type.  Those data nodes are inserted via
   augmentation into the link and termination-point lists, respectively.
   Again, data nodes can be defined as conditional on the presence of
   the corresponding network type in the containing network, by adding a
   corresponding "when" statement.

   It is possible, but not required, to group data nodes for a given
   network type under a dedicated container.  Doing so introduces
   additional structure but lengthens data node path names.

Top      ToC       Page 14 
   In cases where a hierarchy of network types is defined, augmentations
   can in turn be applied against augmenting modules, with the module of
   a network whose type is more specific augmenting the module of a
   network whose type is more general.

4.4.  Discussion and Selected Design Decisions

4.4.1.  Container Structure

   Rather than maintaining lists in separate containers, the data model
   is kept relatively flat in terms of its containment structure.  Lists
   of nodes, links, termination points, and supporting nodes; supporting
   links; and supporting termination points are not kept in separate
   containers.  Therefore, path identifiers that are used to refer to
   specific nodes -- in management operations or in specifications of
   constraints -- can remain relatively compact.  Of course, this means
   that there is no separate structure in instance information that
   separates elements of different lists from one another.  Such a
   structure is semantically not required, but it might provide enhanced
   "human readability" in some cases.

4.4.2.  Underlay Hierarchies and Mappings

   To minimize assumptions regarding what a particular entity might
   actually represent, mappings between networks, nodes, links, and
   termination points are kept strictly generic.  For example, no
   assumptions are made regarding whether a termination point actually
   refers to an interface or whether a node refers to a specific
   "system" or device; the data model at this generic level makes no
   provisions for these.

   Where additional specifics about mappings between upper and lower
   layers are required, the information can be captured in augmenting
   modules.  For example, to express that a termination point in a
   particular network type maps to an interface, an augmenting module
   can introduce an augmentation to the termination point.  The
   augmentation introduces a leaf of type "interface-ref".  That leaf
   references the corresponding interface [RFC8343].  Similarly, if a
   node maps to a particular device or network element, an augmenting
   module can augment the node data with a leaf that references the
   network element.

Top      ToC       Page 15 
   It is possible for links at one level of a hierarchy to map to
   multiple links at another level of the hierarchy.  For example, a VPN
   topology might model VPN tunnels as links.  Where a VPN tunnel maps
   to a path that is composed of a chain of several links, the link will
   contain a list of those supporting links.  Likewise, it is possible
   for a link at one level of a hierarchy to aggregate a bundle of links
   at another level of the hierarchy.

4.4.3.  Dealing with Changes in Underlay Networks

   It is possible for a network to undergo churn even as other networks
   are layered on top of it.  When a supporting node, link, or
   termination point is deleted, the supporting leafrefs in the overlay
   will be left dangling.  To allow for this possibility, the data model
   makes use of the "require-instance" construct of YANG 1.1 [RFC7950].

   A dangling leafref of a configured object leaves the corresponding
   instance in a state in which it lacks referential integrity,
   effectively rendering it nonoperational.  Any corresponding object
   instance is therefore removed from the operational state datastore
   until the situation has been resolved, i.e., until either (1) the
   supporting object is added to the operational state datastore or
   (2) the instance is reconfigured to refer to another object that is
   actually reflected in the operational state datastore.  It will
   remain part of the intended datastore.

   It is the responsibility of the application maintaining the overlay
   to deal with the possibility of churn in the underlay network.  When
   a server receives a request to configure an overlay network, it
   SHOULD validate whether supporting nodes / links / termination points
   refer to nodes in the underlay that actually exist, i.e., verify that
   the nodes are reflected in the operational state datastore.
   Configuration requests in which supporting nodes / links /
   termination points refer to objects currently not in existence SHOULD
   be rejected.  It is the responsibility of the application to update
   the overlay when a supporting node / link / termination point is
   deleted at a later point in time.  For this purpose, an application
   might subscribe to updates when changes to the underlay occur -- for
   example, using mechanisms defined in [YANG-Push].

4.4.4.  Use of Groupings

   The data model makes use of groupings instead of simply defining data
   nodes "inline".  This makes it easier to include the corresponding
   data nodes in notifications, which then do not need to respecify each
   data node that is to be included.  The trade-off is that it makes the
   specification of constraints more complex, because constraints
   involving data nodes outside the grouping need to be specified in

Top      ToC       Page 16 
   conjunction with a "uses" statement where the grouping is applied.
   This also means that constraints and XML Path Language (XPath)
   statements need to be specified in such a way that they navigate
   "down" first and select entire sets of nodes, as opposed to being
   able to simply specify them against individual data nodes.

4.4.5.  Cardinality and Directionality of Links

   The topology data model includes links that are point-to-point and
   unidirectional.  It does not directly support multipoint and
   bidirectional links.  Although this may appear as a limitation, the
   decision to do so keeps the data model simple and generic, and it
   allows it to be very easily subjected to applications that make use
   of graph algorithms.  Bidirectional connections can be represented
   through pairs of unidirectional links.  Multipoint networks can be
   represented through pseudonodes (similar to IS-IS, for example).  By
   introducing hierarchies of nodes with nodes at one level mapping onto
   a set of other nodes at another level and by introducing new links
   for nodes at that level, topologies with connections representing
   non-point-to-point communication patterns can be represented.

4.4.6.  Multihoming and Link Aggregation

   Links are terminated by a single termination point, not sets of
   termination points.  Connections involving multihoming or link
   aggregation schemes need to be represented using multiple point-to-
   point links and then defining a link at a higher layer that is
   supported by those individual links.

4.4.7.  Mapping Redundancy

   In a hierarchy of networks, there are nodes mapping to nodes, links
   mapping to links, and termination points mapping to termination
   points.  Some of this information is redundant.  Specifically, if the
   mapping of a link to one or more other links is known and the
   termination points of each link are known, the mapping information
   for the termination points can be derived via transitive closure and
   does not have to be explicitly configured.  Nonetheless, in order to
   not constrain applications regarding which mappings they want to
   configure and which should be derived, the data model provides the
   option to configure this information explicitly.  The data model
   includes integrity constraints to allow for validating for

Top      ToC       Page 17 
4.4.8.  Typing

   A network's network types are represented using a container that
   contains a data node for each of its network types.  A network can
   encompass several types of networks simultaneously; hence, a
   container is used instead of a case construct, with each network type
   in turn represented by a dedicated presence container.  The reason
   for not simply using an empty leaf, or (even more simply) even doing
   away with the network container and just using a leaf-list of
   "network-type" instead, is to be able to represent "class
   hierarchies" of network types, with one network type "refining" the
   other.  Containers specific to a network type are to be defined in
   the network-specific modules, augmenting the network-types container.

4.4.9.  Representing the Same Device in Multiple Networks

   One common requirement concerns the ability to indicate that the same
   device can be part of multiple networks and topologies.  However, the
   data model defines a node as relative to the network that contains
   it.  The same node cannot be part of multiple topologies.  In many
   cases, a node will be the abstraction of a particular device in a
   network.  To reflect that the same device is part of multiple
   topologies, the following approach might be chosen: a new type of
   network to represent a "physical" (or "device") network is
   introduced, with nodes representing devices.  This network forms an
   underlay network for logical networks above it, with nodes of the
   logical network mapping onto nodes in the physical network.

   This scenario is depicted in Figure 6.  This figure depicts three
   networks with two nodes each.  A physical network ("P" in the figure)
   consists of an inventory of two nodes (D1 and D2), each representing
   a device.  A second network, X, has a third network, Y, as its
   underlay.  Both X and Y also have the physical network (P) as their
   underlay.  X1 has both Y1 and D1 as underlay nodes, while Y1 has D1
   as its underlay node.  Likewise, X2 has both Y2 and D2 as underlay
   nodes, while Y2 has D2 as its underlay node.  The fact that X1 and Y1
   are both instantiated on the same physical node (D1) can be
   easily seen.

Top      ToC       Page 18 
                        /   [X1]____[X2]      /  X(Service Overlay)
                         ..:    :..: :
                ........:     ....: : :....
         +-----:-------------:--+    :     :...
        /   [Y1]____[Y2]....:  /      :..      :
       +------|-------|-------+          :..    :...
        Y(L3) |       +---------------------:-----+ :
              |                         +----:----|-:----------+
              +------------------------/---[D1]  [D2]         /
                                        P (Physical Network)

         Figure 6: Topology Hierarchy Example - Multiple Underlays

   In the case of a physical network, nodes represent physical devices
   and termination points represent physical ports.  It should be noted
   that it is also possible to augment the data model for a physical
   network type, defining augmentations that have nodes reference system
   information and termination points reference physical interfaces, in
   order to provide a bridge between network and device models.

4.4.10.  Supporting Client-Configured and System-Controlled Network

   YANG requires data nodes to be designated as either configuration
   data ("config true") or operational data ("config false"), but not
   both, yet it is important to have all network information, including
   vertical cross-network dependencies, captured in one coherent data
   model.  In most cases, network topology information about a network
   is discovered; the topology is considered a property of the network
   that is reflected in the data model.  That said, certain types of
   topologies need to also be configurable by an application, e.g., in
   the case of overlay topologies.

   The YANG data model for network topologies designates all data as
   "config true".  The distinction between data that is actually
   configured and data that is in effect, including network data that is
   discovered, is provided through the datastores introduced as part of
   the Network Management Datastore Architecture (NMDA) [RFC8342].
   Network topology data that is discovered is automatically populated
   as part of the operational state datastore, i.e., <operational>.  It
   is "system controlled".  Network topology that is configured is
   instantiated as part of a configuration datastore, e.g., <intended>.
   Only when it has actually taken effect will it also be instantiated
   as part of the operational state datastore, i.e., <operational>.

Top      ToC       Page 19 
   In general, a configured network topology will refer to an underlay
   topology and include layering information, such as the supporting
   node(s) underlying a node, supporting link(s) underlying a link, and
   supporting termination point(s) underlying a termination point.  The
   supporting objects must be instantiated in the operational state
   datastore in order for the dependent overlay object to be reflected
   in the operational state datastore.  Should a configured data item
   (such as a node) have a dangling reference that refers to a
   nonexistent data item (such as a supporting node), the configured
   data item will automatically be removed from <operational> and show
   up only in <intended>.  It will be up to the client application to
   resolve the situation and ensure that the reference to the supporting
   resources is configured properly.

   For each network, the origin of its data is indicated per the
   "origin" metadata [RFC7952] annotation defined in [RFC8342].  In
   general, the origin of discovered network data is "learned"; the
   origin of configured network data is "intended".

4.4.11.  Identifiers of String or URI Type

   The current data model defines identifiers of nodes, networks, links,
   and termination points as URIs.  Alternatively, they could have been
   defined as strings.

   The case for strings is that they will be easier to implement.  The
   reason for choosing URIs is that the topology / node / termination
   point exists in a larger context; hence, it is useful to be able to
   correlate identifiers across systems.  Although strings -- being the
   universal data type -- are easier for human beings, they also muddle
   things.  What typically happens is that strings have some structure
   that is magically assigned, and the knowledge of this structure has
   to be communicated to each system working with the data.  A URI makes
   the structure explicit and also attaches additional semantics: the
   URI, unlike a free-form string, can be fed into a URI resolver, which
   can point to additional resources associated with the URI.  This
   property is important when the topology data is integrated into a
   larger and more complex system.

(page 19 continued on part 2)

Next Section