Network Working Group
Internet Engineering Task Force (IETF)                          A. Clemm
Internet-Draft
Request for Comments: 8345                                        Huawei
Intended status:
Category: Standards Track                                      J. Medved
Expires: June 21, 2018
ISSN: 2070-1721                                                    Cisco
                                                                R. Varga
                                               Pantheon Technologies SRO
                                                              N. Bahadur
                                                       Bracket Computing
                                                      H. Ananthakrishnan
                                                           Packet Design
                                                                  X. Liu
                                                                   Jabil
                                                       December 18, 2017
                                                              March 2018

                A YANG Data Model for Network Topologies
                draft-ietf-i2rs-yang-network-topo-20.txt

Abstract

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

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 an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list  It represents the consensus of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid the IETF community.  It has
   received public review and has been approved for a maximum publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of six months RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be updated, replaced, or obsoleted by other documents obtained 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 June 21, 2018.
   https://www.rfc-editor.org/info/rfc8345.

Copyright Notice

   Copyright (c) 2017 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
   (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 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.

Table of Contents

   1. Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3 ....................................................4
   2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . .   7 .......................................................8
   3. Definitions and Acronyms  . . . . . . . . . . . . . . . . . .   7 Abbreviations ...................................9
   4. Model Structure Details . . . . . . . . . . . . . . . . . . .   8 .........................................9
      4.1. Base Network Model  . . . . . . . . . . . . . . . . . . .   8 .........................................9
      4.2. Base Network Topology Data Model  . . . . . . . . . . . .  10 ..........................12
      4.3. Extending the data model  . . . . . . . . . . . . . . . .  12 Data Model ..................................13
      4.4. Discussion and selected design decisions  . . . . . . . .  12 Selected Design Decisions ..................14
           4.4.1. Container structure . . . . . . . . . . . . . . . . .  12 Structure ................................14
           4.4.2. Underlay hierarchies Hierarchies and mappings . . . . . . . . . .  13 Mappings ..................14
           4.4.3. Dealing with changes Changes in underlay networks . . . . . .  13 Underlay Networks ..........15
           4.4.4. Use of groupings  . . . . . . . . . . . . . . . . . .  14 Groupings ...................................15
           4.4.5. Cardinality and directionality Directionality of links . . . . . . .  14 Links ............16
           4.4.6. Multihoming and link aggregation  . . . . . . . . . .  15 Link Aggregation ...................16
           4.4.7. Mapping redundancy  . . . . . . . . . . . . . . . . .  15 Redundancy .................................16
           4.4.8. Typing  . . . . . . . . . . . . . . . . . . . . . . .  15 .............................................17
           4.4.9. Representing the same device Same Device in multiple networks . .  15 Multiple Networks ..17
           4.4.10. Supporting client-configured Client-Configured and system-controlled
               network topology  . . . . . . . . . . . . . . . . . .  16
                   System-Controlled Network Topologies ..............18
           4.4.11. Identifiers of string String or URI type . . . . . . . . . .  17 Type .................19
   5. Interactions with Other YANG Modules  . . . . . . . . . . . .  18 ...........................19
   6. YANG Modules  . . . . . . . . . . . . . . . . . . . . . . . .  18 ...................................................20
      6.1. Defining the Abstract Network: ietf-network.yang  . . . .  18 ietf-network ...............20
      6.2. Creating Abstract Network Topology: ietf-network-
           topology.yang . . . . . . . . . . . . . . . . . . . . . .  23
           ietf-network-topology .....................................25
   7. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  29 ............................................32
   8. Security Considerations . . . . . . . . . . . . . . . . . . .  30 ........................................33
   9.  Contributors  . . . . . . . . . . . . . . . . . . . . . . . .  32
   10. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  32
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  33
     11.1. .....................................................35
      9.1. Normative References . . . . . . . . . . . . . . . . . .  33
     11.2. ......................................35
      9.2. Informative References . . . . . . . . . . . . . . . . .  34 ....................................36
   Appendix A. Model Use Cases  . . . . . . . . . . . . . . . . . .  36 .......................................38
     A.1. Fetching Topology from a Network Element  . . . . . . . .  36 ...................38
     A.2. Modifying TE Topology Imported from an Optical Controller  36 ..38
     A.3. Annotating Topology for Local Computation . . . . . . . .  37 ..................39
     A.4. SDN Controller-Based Configuration of Overlays on Top of
          Underlays . . . . . . . . . . . . . . . . . . . . . . . .  37 ..................................................39
   Appendix B. Companion YANG models Data Models for non-NMDA compliant
                implementations  . . . . . . . . . . . . . . . . . .  37 Implementations Not
               Compliant with NMDA ...................................39
     B.1. YANG Model Module for Network State  . . . . . . . . . . . . . .  38 ..............................40
     B.2. YANG Data Model Module for Network Topology State  . . . . . . .  42 .....................45
   Appendix C. An Example . . . . . . . . . . . . . . . . . . . . .  48 ............................................52
   Acknowledgments ...................................................56
   Contributors ......................................................56
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  52 ................................................57

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. parts: The first part of the data model defines a
   network data model that enables the definition of network hierarchies
   (i.e.
   hierarchies, or network stacks of (i.e., networks that are layered on
   top of each other) and to maintain 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 "links" and termination points
   "termination points" to describe how nodes in a network are connected
   to each other.
   Moreover  Moreover, the data model introduces vertical layering
   relationships between networks that can be augmented to cover both
   network inventories and network/service topologies.

   While

   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 to augment network
   inventory information separately to be augmented separately, and without concern
   for topology 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,
   topologies; Layer 3 network topologies, topologies such as Unicast unicast IGP, IS-IS
   [RFC1195]
   [RFC1195], and OSPF [RFC2328], [RFC2328]; traffic engineering (TE) data
   [RFC3209],
   [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 does 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.yang", "ietf-network" (Section 6.1), contains a list of abstract
   network nodes and defines the concept of network hierarchy "network hierarchy" (network
   stack).  The abstract network node can be augmented in inventory and
   topology data models with inventory inventory-specific and topology specific topology-specific
   attributes.  Network  The network hierarchy (stack) allows any given network
   to have one or more "supporting networks".  The relationship of between
   the base network data model, the inventory data models models, and the
   topology data models is shown in the following figure 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 Network Data Model Structure

   The network-topology YANG module introduced in this document,
   entitled "ietf-network-topology.yang", "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 edges, and termination points.  Nodes (from the ietf-
   network.yang
   "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, topologies -- for example example,
   topologies at different layers and overlay topologies.  The data
   model therefore allows to capture relationships between topologies, as well as
   dependencies between nodes and termination points across
   topologies. topologies,
   to be captured.  An example of a topology stack is shown in the following
   figure. Figure 2.

                    +---------------------------------------+
                   /            _[X1]_          "Service"  /
                  /           _/  :   \_                  /
                 /          _/     :    \_               /
                /         _/        :     \_            /
               /         /           :      \          /
              /       [X2]__________________[X3]      /
             +---------:--------------:------:-------+
                        :              :     :
                    +----:--------------:----:--------------+
                   /      :              :   :        "L3" /
                  /        :              :  :            /
                 /         :               : :           /
                /         [Y1]_____________[Y2]         /
               /           *               * *         /
              /            *              *  *        /
             +--------------*-------------*--*-------+
                             *           *   *
                    +--------*----------*----*--------------+
                   /     [Z1]_______________[Z1]     [Z1]_______________[Z2] "Optical" /
                  /         \_         *   _/             /
                 /            \_      *  _/              /
                /               \_   * _/               /
               /                  \ * /                /
              /                    [Z]                /
             +---------------------------------------+

               Figure 2: Topology hierarchy (stack) example

   The figure 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) (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.
   The figure shows two Service Functions
   Two service functions (X1 and X3) mapping are mapped onto a single L3 network
   element (Y2); this could happen, for example, if two service
   functions reside in the same VM Virtual Machine (VM) (or server) and
   share the same set of network interfaces.  The figure shows a  A single "L3" network
   element (Y2) is mapped onto multiple two "Optical" network elements
   (Z (Z2 and Z1).
   Z).  This could happen, for example, if a single IP router attaches
   to multiple Reconfigurable Optical Add/Drop Multiplexers (ROADMs) in
   the optical domain.

   Another example of a service topology stack is shown in the following
   figure. Figure 3.

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

               Figure 3: Topology hierarchy (stack) example

   The figure 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 I2RS, 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 that where the data model can be applied to are
   described in [I-D.draft-ietf-i2rs-usecase-reqs-summary]. [USECASE-REQS].

   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
   but controlled;
   rather, it is configured by a client.

   The data model allows a network to refer to a supporting-network,
   supporting-nodes, supporting-links, supporting network,
   supporting nodes, supporting links, etc.  The data model also allows
   to layer
   the layering of a network that is configured on top of one 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 [I-D.draft-ietf-netmod-revised-datastores], [RFC8342], the requirements for which are defined as
   requirement Ephemeral-REQ-03
   in Section 3 of [RFC8242].  This allows network topology data that is
   written, i.e. i.e., configured by a client and not system controlled, to
   refer to a 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
   IP-routed network topology.  When an implementation places written
   data for this data model in the ephemeral data store, then 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",
   "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.

3.  Definitions and Acronyms 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 adopted tree (definition from
   [I-D.draft-ietf-netmod-revised-datastores])
      [RFC8342]).

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

   IGP:  Interior Gateway Protocol Protocol.

   IS-IS:  Intermediate System to Intermediate System protocol System.

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

   SDN:  Software-Defined Networking.

   URI:  Uniform Resource Identifier 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.yang
   "ietf-network" module.  Its structure is shown in the following figure. Figure 4.  The
   notation syntax follows
   [I-D.draft-ietf-netmod-yang-tree-diagrams]. 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       -> ../../../supporting-network/network-ref
                 +--rw node-ref       -> /networks/network/node/node-id

     Figure 4: The structure Structure of the abstract (base) network data model Abstract (Base) Network Data Model
   The data model contains a container with a list of networks.  Each
   network is captured in its own list entry, distinguished via a
   network-id.

   A network has a certain type, such as L2, L3, OSPF OSPF, or IS-IS.  A
   network can even have multiple types simultaneously.  The type, type or
   types,
   types are captured underneath the container "network-types".  In this module
   model, it serves merely as an augmentation target; network-
   specific network-specific
   modules will later introduce new data nodes to represent new network
   types below this target, i.e. i.e., will insert them below "network-
   types" by ways of "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 empty type. 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 Layer 3 unicast IGP network) would contain
   underneath "network-
   types" "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
   [I-D.draft-ietf-i2rs-yang-l3-topology]. [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 is, in effect 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 instead, it is a part of the network that it is contained in. 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 that of which it a is part of. a part.  To represent indicate
   that the same entity or same 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, respectively
   network -- the (entities) nodes (entities) in that network, 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
   allows for the definition of more than one underlay network (and
   node), allowing for simultaneous representation of layered network
   topologies and service topologies topologies, and their physical instantiation.

   Similar to a network, a node can be supported by other nodes, 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 allows 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, example:

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

   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.  In one way, ways: (1) the network data is configured by client
   applications,
   applications -- for example example, in the case of overlay networks that are
   configured by an SDN Controller application.  In another way, it 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
   [I-D.draft-ietf-netmod-revised-datastores] [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, 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 is, in addition 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) Controller) to resolve the situation and ensure that
   the reference to the supporting resources is configured properly.

4.2.  Base Network Topology Data Model

   The abstract (base) network topology data model is defined in the
   "ietf-network-topology.yang"
   "ietf-network-topology" module.  It builds on the network data model
   defined in the "ietf-network.yang" "ietf-network" module, augmenting it with links
   (defining how nodes are connected) and termination-points termination points (which
   anchor the links and are contained in nodes).  The structure of the
   network topology module is shown in the following figure. Figure 5.  The notation syntax
   follows [I-D.draft-ietf-netmod-yang-tree-diagrams]. 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?     -> ../../../nw:node[nw:node-id=current()/+
      |                       ../source-node]/termination-point/tp-id     leafref
          +--rw destination
          |  +--rw dest-node?   -> ../../../nw:node/node-id
          |  +--rw dest-tp?     -> ../../../nw:node[nw:node-id=current()/+
      |                     ../dest-node]/termination-point/tp-id     leafref
          +--rw supporting-link* [network-ref link-ref]
             +--rw network-ref    -> ../../../nw:supporting-network/+
             |                    network-ref       -> ../../../nw:supporting-network/network-ref
             +--rw link-ref       -> /nw:networks/network+
                              [nw:network-id=current()/../network-ref]/+
                              link/link-id       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         -> /nw:networks/network[nw:network-id=+
                              current()/../network-ref]/node+
                              [nw:node-id=current()/../node-ref]/+
                              termination-point/tp-id         leafref

      Figure 5: The structure Structure of the abstract (base) network topology data
                                   model 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.

   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 in an underlay topology (which are terminated by
   the corresponding underlay termination
   points). points) in an underlay
   topology.  This is captured in the list "supporting-link".

4.3.  Extending the data model 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: for the new network type, a new YANG module for the new network type is introduced.
   In this module, a number of augmentations are defined against the
   network
   "ietf-network" and network-topology YANG "ietf-network-topology" modules.

   We start with augmentations against the ietf-network.yang "ietf-network" module.
   First, a new network type needs to be defined.  For this, defined; this is done by
   defining a presence container that represents the new network type.
   The new network type is defined.  It is
   inserted inserted, by means of augmentation augmentation, below the
   network-types container.  Subsequently, data nodes for any network-type specific node
   parameters that are defined and augmented into 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 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
   constraints.

   Subsequently, augmentations are defined against ietf-network-
   topology.yang. the
   "ietf-network-topology" module.  Data nodes are defined both for link
   parameters, as well as termination point parameters, that are
   specific to the new network type.  Those data nodes are inserted by way of 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 network type in the containing network, by adding a
   corresponding "when"-statement. "when" statement.

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

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

4.4.  Discussion and selected design decisions Selected Design Decisions

4.4.1.  Container structure 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, termination points, and supporting-nodes,
   supporting-links, supporting nodes; supporting
   links; and supporting-termination-points supporting termination points are not kept in separate
   containers.  Therefore, path identifiers that are used to refer to
   specific nodes, be it nodes -- in management operations or in specifications of constraints,
   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, although but it might enhance human readability provide enhanced
   "human readability" in some cases.

4.4.2.  Underlay hierarchies Hierarchies and mappings Mappings

   To minimize assumptions of 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, interface or whether a node refers to a specific
   "system" or device; the data model at this generic level makes no
   provisions for that. these.

   Where additional specifics about mappings between upper and lower
   layers are required, those 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 which point.  The
   augmentation introduces a leaf of type ifref that "interface-ref".  That leaf
   references the corresponding interface [RFC7223]. [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.

   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 Changes in underlay networks 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 in effect inoperational. nonoperational.  Any corresponding object
   instance is therefore removed from the operational state datastore
   until the situation has been resolved, i.e. i.e., until either (1) the
   supporting object is added to the operational state datastore, datastore or
   until
   (2) the instance is reconfigured to refer to another object that is
   actually reflected in the operational state datastore.  It does 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/tps nodes / links / termination points
   refer to nodes in the underlay are that actually in existence, i.e. exist, i.e., verify that
   the nodes which are reflected in the operational state datastore.
   Configuration requests in which supporting nodes/links/tps 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/tp 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, occur -- for
   example
   example, using mechanisms defined in
   [I-D.draft-ietf-netconf-yang-push]. [YANG-Push].

4.4.4.  Use of groupings Groupings

   The data model makes use of groupings, groupings instead of simply defining data
   nodes "in-line". "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 tradeoff for
   this 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
   conjunction with a "uses" statement where the grouping is applied.
   This also means that constraints and XPath- 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 Directionality of links Links

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

4.4.6.  Multihoming and link aggregation 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, links and then defining a link at a higher layer that is
   supported by those individual links.

4.4.7.  Mapping redundancy 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
   link-to-links
   mapping of a link to one or more other links is known, known and the
   termination points of each link are known, termination point 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 does provide for provides the
   option to configure this information explicitly.  The data model
   includes integrity constraints to allow for validating for
   consistency.

4.4.8.  Typing

   A network's network types are represented using a container which that
   contains a data node for each of its network types.  A network can
   encompass several types of network simultaneously, hence networks simultaneously; hence, a
   container is used instead of a case construct, with each network type
   in turn represented by a dedicated presence container itself. container.  The reason
   for not simply using an empty leaf, or (even more simply) even simpler, do doing
   away even with the network container and just use using a leaf-list of network-type
   "network-type" instead, is to be able to represent "class
   hierarchies" of network types, with one network type refining "refining" the
   other.  Network-type  Containers specific containers 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 Same Device in multiple networks Multiple Networks

   One common requirement concerns the ability to represent 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 it is contained in. 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 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 the following figure.  It Figure 6.  This figure depicts three
   networks with two nodes each.  A physical network P ("P" in the figure)
   consists of an inventory of two nodes, D1 nodes (D1 and D2, 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 (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 (D1) can be
   easily derived. seen.

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

         Figure 6: Topology hierarchy example Hierarchy Example - multiple underlays 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,
   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 Client-Configured and system-controlled network
         topology System-Controlled Network
         Topologies

   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 is discovered about a network; network
   is discovered; the topology is considered a property of the network
   that is reflected in the data model.  That said, certain types of
   topology
   topologies need to also be configurable by an application, such as e.g., in
   the case of overlay topologies.

   The YANG data model for network topology 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 about the network,
   discovered, is provided through the datastores introduced as part of
   the Network Management Datastore Architecture,
   NMDA [I-D.draft-ietf-netmod-revised-datastores]. 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. e.g., <intended>.
   Only when it has actually taken effect, effect will it is also be instantiated
   as part of the operational state datastore, i.e. i.e., <operational>.

   Configured

   In general, a configured network topology will in general 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 non-
   existing
   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
   [I-D.draft-ietf-netmod-revised-datastores]. [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 String or URI type Type

   The current data model defines identifiers of nodes, networks, links,
   and termination points as URIs.  An alternative would define them  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/tp topology / node / termination
   point exists in a larger context, hence context; hence, it is useful to be able to
   correlate identifiers across systems.  While strings,  Although strings -- being the
   universal data
   type, type -- are easier for human beings, they also muddle
   things.  What typically happens is that strings have some structure which
   that is magically assigned 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,
   larger and more complex system.

5.  Interactions with Other YANG Modules

   The data model makes use of data types that have been defined in
   [RFC6991].

   This is a protocol independent protocol-independent YANG data model with topology
   information.  It is separate from from, and not linked with with, data models
   that are used to configure routing protocols or routing information.
   This includes e.g. data model includes, for example, the "ietf-routing" YANG module [RFC8022].

   The data model obeys the requirements for the ephemeral state found as
   specified in the document [RFC8242].  For ephemeral topology data that is system
   controlled, the process tasked with maintaining topology information
   will load information from the routing process (such as OSPF) into
   the operational state datastore without relying on a configuration
   datastore.

6.  YANG Modules

6.1.  Defining the Abstract Network: ietf-network.yang

   NOTE TO RFC EDITOR: Please change the date in the file name after the
   CODE BEGINS statement to the date of publication when published. ietf-network

   <CODE BEGINS> file "ietf-network@2017-12-18.yang" "ietf-network@2018-02-26.yang"

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

     import ietf-inet-types {
       prefix inet;
       reference
         "RFC 6991"; 6991: Common YANG Data Types";
     }

     organization
       "IETF I2RS (Interface to the Routing System) Working Group";

     contact
       "WG Web:    <http://tools.ietf.org/wg/i2rs/>    <https://datatracker.ietf.org/wg/i2rs/>
        WG List:   <mailto:i2rs@ietf.org>

        Editor:    Alexander Clemm
                   <mailto:ludwig@clemm.org>

        Editor:    Jan Medved
                   <mailto:jmedved@cisco.com>

        Editor:    Robert Varga
                   <mailto:robert.varga@pantheon.tech>

        Editor:    Nitin Bahadur
                   <mailto:nitin_bahadur@yahoo.com>

        Editor:    Hariharan Ananthakrishnan
                   <mailto:hari@packetdesign.com>

        Editor:    Xufeng Liu
                   <mailto:Xufeng_Liu@jabil.com>";
                   <mailto:xufeng.liu.ietf@gmail.com>";
     description
       "This module defines a common base data model for a collection
        of nodes in a network.  Node definitions are further used
        in network topologies and inventories.

        Copyright (c) 2017 2018 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 Simplified BSD License
        set forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
        (http://trustee.ietf.org/license-info).
        (https://trustee.ietf.org/license-info).

        This version of this YANG module is part of
        draft-ietf-i2rs-yang-network-topo-20; RFC 8345;
        see the RFC itself for full legal notices.

        NOTE TO RFC EDITOR: Please replace above reference to
        draft-ietf-i2rs-yang-network-topo-20 with RFC
        number when published (i.e. RFC xxxx)."; notices.";

     revision 2017-12-18 2018-02-26 {
       description
         "Initial revision.
          NOTE TO RFC EDITOR:
          (1) Please replace the following reference
          to draft-ietf-i2rs-yang-network-topo-20 with
          RFC number when published (i.e. RFC xxxx).
          (2) Please replace the date in the revision statement with the
          date of publication when published. "; revision.";
       reference
         "draft-ietf-i2rs-yang-network-topo-20";
         "RFC 8345: A YANG Data Model for Network Topologies";
     }

     typedef node-id {
       type inet:uri;
       description
         "Identifier for a node.  The precise structure of the node-id
          will be up to the implementation.  Some  For example, some
          implementations MAY
          for example, pick a uri URI that includes the network-id
          as part of the path.  The identifier SHOULD be chosen
          such that the same node in a real network topology will
          always be identified through the same identifier, even if
          the data model is instantiated in separate datastores.  An
          implementation MAY choose to capture semantics in the identifier,
          identifier -- for example example, to indicate the type of node.";
     }
     typedef network-id {
       type inet:uri;
       description
         "Identifier for a network.  The precise structure of the
          network-id will be up to an the implementation.  The identifier
          SHOULD be chosen such that the same network will always be
          identified through the same identifier, even if the data model
          is instantiated in separate datastores.  An implementation MAY
          choose to capture semantics in the
         identifier, identifier -- for example example,
          to indicate the type of network.";
     }

     grouping network-ref {
       description
         "Contains the information necessary to reference a network, network --
          for example example, an underlay network.";
       leaf network-ref {
         type leafref {
           path "/nw:networks/nw:network/nw:network-id";
         require-instance false;
         }
         description
           "Used to reference a network, network -- for example example, an underlay
            network.";
       }
     }

     grouping node-ref {
       description
         "Contains the information necessary to reference a node.";
       leaf node-ref {
         type leafref {
           path "/nw:networks/nw:network[nw:network-id=current()/../"+
             "network-ref]/nw:node/nw:node-id";
           require-instance false;
         }
         description
           "Used to reference a node.
            Nodes are identified relative to the network they are
            contained in."; that
            contains them.";
       }
       uses network-ref;
     }
     container networks {
       description
         "Serves as a top-level container for a list of networks.";
       list network {
         key "network-id";
         description
           "Describes a network.
            A network typically contains an inventory of nodes,
            topological information (augmented through the
            network-topology data model), as well as and layering information.";
         leaf network-id {
           type network-id;
           description
             "Identifies a network.";
         }
         container network-types {
           description
             "Serves as an augmentation target.
              The network type is indicated through corresponding
              presence containers augmented into this container.";
         }
         list supporting-network {
           key "network-ref";
           description
             "An underlay network, used to represent layered network
              topologies.";
           leaf network-ref {
             type leafref {
               path "/nw:networks/nw:network/nw:network-id";
             require-instance false;
             }
             description
               "References the underlay network.";
           }
         }
         list node {
           key "node-id";
           description
             "The inventory of nodes of this network.";
           leaf node-id {
             type node-id;
             description
               "Identifies
               "Uniquely identifies a node uniquely within the containing
                network.";
           }
           list supporting-node {
             key "network-ref node-ref";
             description
               "Represents another node, node that is in an underlay network, network
                and that supports this node is supported by. node.  Used to represent layering
                structure.";
             leaf network-ref {
               type leafref {
                 path "../../../nw:supporting-network/nw:network-ref";
               require-instance false;
               }
               description
                 "References the underlay network that of which the
                  underlay node is part of."; a part.";
             }
             leaf node-ref {
               type leafref {
                 path "/nw:networks/nw:network/nw:node/nw:node-id";
               require-instance false;
               }
               description
                 "References the underlay node itself.";
             }
           }
         }
       }
     }
   }

   <CODE ENDS>

6.2.  Creating Abstract Network Topology: ietf-network-topology.yang

   NOTE TO RFC EDITOR: Please change the date in the file name after the
   CODE BEGINS statement to the date of publication when published. ietf-network-topology

   <CODE BEGINS> file "ietf-network-topology@2017-12-18.yang" "ietf-network-topology@2018-02-26.yang"

   module ietf-network-topology {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology";
     prefix nt;

     import ietf-inet-types {
       prefix inet;
       reference
         "RFC 6991"; 6991: Common YANG Data Types";
     }
     import ietf-network {
       prefix nw;
       reference
       "draft-ietf-i2rs-yang-network-topo-20
       NOTE TO RFC EDITOR:
       (1) Please replace above reference to
       draft-ietf-i2rs-yang-network-topo-20 with RFC
       number when published (i.e. RFC xxxx).
       (2) Please replace the date in the revision statement with the
        date of publication when published.";
         "RFC 8345: A YANG Data Model for Network Topologies";
     }

     organization
       "IETF I2RS (Interface to the Routing System) Working Group";

     contact
       "WG Web:    <http://tools.ietf.org/wg/i2rs/>    <https://datatracker.ietf.org/wg/i2rs/>
        WG List:   <mailto:i2rs@ietf.org>

        Editor:    Alexander Clemm
                   <mailto:ludwig@clemm.org>

        Editor:    Jan Medved
                   <mailto:jmedved@cisco.com>

        Editor:    Robert Varga
                   <mailto:robert.varga@pantheon.tech>

        Editor:    Nitin Bahadur
                   <mailto:nitin_bahadur@yahoo.com>

        Editor:    Hariharan Ananthakrishnan
                   <mailto:hari@packetdesign.com>

        Editor:    Xufeng Liu
                 <mailto:Xufeng_Liu@jabil.com>";
                   <mailto:xufeng.liu.ietf@gmail.com>";
     description
       "This module defines a common base model for a network topology,
        augmenting the base network data model with links to connect
        nodes, as well as termination points to terminate links
        on nodes.

        Copyright (c) 2017 2018 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 Simplified BSD License
        set forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
      (http://trustee.ietf.org/license-info).
        (https://trustee.ietf.org/license-info).

        This version of this YANG module is part of
      draft-ietf-i2rs-yang-network-topo-20; RFC 8345;
        see the RFC itself for full legal notices.

      NOTE TO RFC EDITOR: Please replace above reference to
      draft-ietf-i2rs-yang-network-topo-20 with RFC
      number when published (i.e. RFC xxxx)."; notices.";

     revision 2017-12-18 2018-02-26 {
       description
         "Initial revision.
        NOTE TO RFC EDITOR: Please replace the following reference
        to draft-ietf-i2rs-yang-network-topo-20 with
        RFC number when published (i.e. RFC xxxx)."; revision.";
       reference
       "draft-ietf-i2rs-yang-network-topo-20";
         "RFC 8345: A YANG Data Model for Network Topologies";
     }

     typedef link-id {
       type inet:uri;
       description
         "An identifier for a link in a topology.  The precise
          structure of the link-id will be up to the implementation.
          The identifier SHOULD be chosen such that the same link in a
          real network topology will always be identified through the
          same identifier, even if the data model is instantiated in
          separate datastores.  An implementation MAY choose to capture
          semantics in the identifier, identifier -- for example example, to indicate the
          type of link and/or the type of topology that of which the link is
          a part
        of."; part.";
     }

     typedef tp-id {
       type inet:uri;
       description
         "An identifier for termination points (TPs) on a node.  The precise
          structure of the tp-id will be up to the implementation.
          The identifier SHOULD be chosen such that the same termination
          point in a real network topology will always be identified
          through the same identifier, even if the data model is
          instantiated in separate datastores.  An implementation MAY
          choose to capture semantics in the identifier, identifier -- for example example,
          to indicate the type of termination point and/or the type of
          node that contains the termination point.";
     }

     grouping link-ref {
       description
         "This grouping can be used to reference a link in a specific
          network.  While  Although it is not used in this module, it is
          defined here for the convenience of augmenting modules.";
       leaf link-ref {
         type leafref {
           path "/nw:networks/nw:network[nw:network-id=current()/../"+
             "network-ref]/nt:link/nt:link-id";
           require-instance false;
         }
         description
           "A type for an absolute reference to a link instance.
            (This type should not be used for relative references.
            In such a case, a relative path should be used instead.)";
       }
       uses nw:network-ref;
     }

     grouping tp-ref {
       description
         "This grouping can be used to references reference a termination point
          in a specific node.  While  Although it is not used in this module,
          it is defined here for the convenience of augmenting
          modules.";
       leaf tp-ref {
         type leafref {
           path "/nw:networks/nw:network[nw:network-id=current()/../"+
             "network-ref]/nw:node[nw:node-id=current()/../"+
             "node-ref]/nt:termination-point/nt:tp-id";
           require-instance false;
         }
         description
           "A type for an absolute reference to a termination point.
            (This type should not be used for relative references.
            In such a case, a relative path should be used instead.)";
       }
       uses nw:node-ref;
     }
     augment "/nw:networks/nw:network" {
       description
         "Add links to the network data model.";
       list link {
         key "link-id";
         description
           "A network link connects a local (source) node and
            a remote (destination) node via a set of the respective
            node's termination points.  It is possible to have several
            links between the same source and destination nodes.
            Likewise, a link could potentially be re-homed between
            termination points.  Therefore, in order to ensure that we
            would always know to distinguish between links, every link
            is identified by a dedicated link identifier.  Note that a
            link models a point-to-point link, not a multipoint link.";
         leaf link-id {
           type link-id;
           description
             "The identifier of a link in the topology.
              A link is specific to a topology to which it belongs.";
         }
         container source {
           description
             "This container holds the logical source of a particular
              link.";
           leaf source-node {
             type leafref {
               path "../../../nw:node/nw:node-id";
               require-instance false;
             }
             description
               "Source node identifier, must identifier.  Must be in the same topology.";
           }
           leaf source-tp {
             type leafref {
               path "../../../nw:node[nw:node-id=current()/../"+
                 "source-node]/termination-point/tp-id";
               require-instance false;
             }
             description
             "Termination
               "This termination point is located within the source node that
                and terminates the link.";
           }
         }
         container destination {
           description
             "This container holds the logical destination of a
              particular link.";
           leaf dest-node {
             type leafref {
               path "../../../nw:node/nw:node-id";
             require-instance false;
             }
             description
               "Destination node identifier, must identifier.  Must be in the same
                network.";
           }
           leaf dest-tp {
             type leafref {
               path "../../../nw:node[nw:node-id=current()/../"+
                 "dest-node]/termination-point/tp-id";
               require-instance false;
             }
             description
             "Termination
               "This termination point is located within the
                destination node that and terminates the link.";
           }
         }
         list supporting-link {
           key "network-ref link-ref";
           description
             "Identifies the link, link or links, that links on which this link
            is dependent on."; depends.";
           leaf network-ref {
             type leafref {
               path "../../../nw:supporting-network/nw:network-ref";
             require-instance false;
             }
             description
               "This leaf identifies in which underlay topology
                the supporting link is present.";
           }
           leaf link-ref {
             type leafref {
               path "/nw:networks/nw:network[nw:network-id=current()/"+
                 "../network-ref]/link/link-id";
               require-instance false;
             }
             description
               "This leaf identifies a link which that is a part
                of this link's underlay.  Reference loops in which
                a link identifies itself as its underlay, either
                directly or transitively, are not allowed.";
           }
         }
       }
     }
     augment "/nw:networks/nw:network/nw:node" {
       description
       "Augment
         "Augments termination points which that terminate links.
          Termination points can ultimately be mapped to interfaces.";
       list termination-point {
         key "tp-id";
         description
           "A termination point can terminate a link.
            Depending on the type of topology, a termination point
            could, for example, refer to a port or an interface.";
         leaf tp-id {
           type tp-id;
           description
             "Termination point identifier.";
         }
         list supporting-termination-point {
           key "network-ref node-ref tp-ref";
           description
             "This list identifies any termination points that
            the on which a
              given termination point is dependent on, depends or maps onto. onto which it maps.
              Those termination points will themselves be contained
              in a supporting node.  This dependency information can be
              inferred from the dependencies between links.  For this reason,  Therefore,
              this item is not separately configurable.  Hence  Hence, no
              corresponding constraint needs to be articulated.
              The corresponding information is simply provided by the
              implementing system.";
           leaf network-ref {
             type leafref {
               path "../../../nw:supporting-node/nw:network-ref";
             require-instance false;
             }
             description
               "This leaf identifies in which topology the
                supporting termination point is present.";
           }
           leaf node-ref {
             type leafref {
               path "../../../nw:supporting-node/nw:node-ref";
             require-instance false;
             }
             description
               "This leaf identifies in which node the supporting
                termination point is present.";
           }
           leaf tp-ref {
             type leafref {
               path "/nw:networks/nw:network[nw:network-id=current()/"+
                 "../network-ref]/nw:node[nw:node-id=current()/../"+
                 "node-ref]/termination-point/tp-id";
               require-instance false;
             }
             description
               "Reference to the underlay node, node (the underlay node must
                be in a different topology"; topology).";
           }
         }
       }
     }
   }

   <CODE ENDS>

7.  IANA Considerations

   This document registers the following namespace URIs in the "IETF XML
   Registry" [RFC3688]:

   URI: urn:ietf:params:xml:ns:yang:ietf-network
   Registrant Contact: The IESG.
   XML: N/A; the requested URI is an XML namespace.

   URI:urn:ietf:params:xml:ns:yang:ietf-network-topology

   URI: urn:ietf:params:xml:ns:yang:ietf-network-topology
   Registrant Contact: The IESG.
   XML: N/A; the requested URI is an XML namespace.

   URI: urn:ietf:params:xml:ns:yang:ietf-network-state
   Registrant Contact: The IESG.
   XML: N/A; the requested URI is an XML namespace.

   URI:urn:ietf:params:xml:ns:yang:ietf-network-topology-state

   URI: urn:ietf:params:xml:ns:yang:ietf-network-topology-state
   Registrant Contact: The IESG.
   XML: N/A; the requested URI is an XML namespace.

   This document registers the following YANG modules in the "YANG
   Module Names" registry [RFC6020]:

   NOTE TO THE RFC EDITOR: In the list below, please replace references
   to "draft-ietf-i2rs-yang-network-topo-20 (RFC form)" with RFC number
   when published (i.e.  RFC xxxx).

   Name:      ietf-network
   Namespace: urn:ietf:params:xml:ns:yang:ietf-network
   Prefix:    nw
   Reference: draft-ietf-i2rs-yang-network-topo-20.txt (RFC form) RFC 8345

   Name:      ietf-network-topology
   Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology
   Prefix:    nt
   Reference: draft-ietf-i2rs-yang-network-topo-20.txt (RFC form) RFC 8345

   Name:      ietf-network-state
   Namespace: urn:ietf:params:xml:ns:yang:ietf-network-state
   Prefix:    nw-s
   Reference: draft-ietf-i2rs-yang-network-topo-20.txt (RFC form) RFC 8345

   Name:      ietf-network-topology-state
   Namespace: urn:ietf:params:xml:ns:yang:ietf-network-topology-state
   Prefix:    nt-s
   Reference: draft-ietf-i2rs-yang-network-topo-20.txt (RFC form) RFC 8345

8.  Security Considerations

   The YANG modules defined specified in this document are define a schema for data
   that is designed to be accessed via network management protocols such
   as NETCONF [RFC6241] or RESTCONF [RFC8040].  The lowest NETCONF layer
   is the secure transport layer, and the mandatory-to-implement secure
   transport is Secure Shell (SSH) [RFC6242].  The lowest RESTCONF layer
   is HTTPS, and the mandatory-to-implement secure transport is TLS
   [RFC5246].

   The NETCONF access control model [RFC6536] [RFC8341] provides the means to
   restrict access for particular NETCONF or RESTCONF users to a
   preconfigured subset of all available NETCONF or RESTCONF protocol
   operations and content.

   The network topology and inventory created by this module reveals these modules reveal
   information about the structure of networks that could be very
   helpful to an attacker.  As a privacy consideration, while although there
   is no personally identifiable information defined in this module, these modules,
   it is possible that some node identifiers may be associated with
   devices that are in turn associated with specific users.

   The YANG modules define information that can be configurable in
   certain instances, instances -- for example example, in the case of overlay topologies
   that can be created by client applications.  In such cases, a
   malicious client could introduce topologies that are undesired.
   Specifically, a malicious client could attempt to remove or add a
   node, a link, or a termination point, point by creating or deleting
   corresponding elements in
   the node, link, and or termination point lists,
   respectively.  In the case of a topology that is learned, the server
   will automatically prohibit such misconfiguration attempts.  In the
   case of a topology that is configured, i.e. i.e., whose origin is
   "intended", the undesired configuration could become effective and be
   reflected in the operational state datastore, leading to disruption
   of services provided via this topology might be disrupted. topology.  For example, the topology
   could be "cut" or could be configured in a suboptimal way, leading to
   increased consumption of resources in the underlay network due to
   resulting the
   routing and bandwidth utilization inefficiencies. inefficiencies that would result.
   Likewise, it could lead to degradation of service levels as well as
   possibly
   possible disruption of service.  For those reasons, it is important
   that the NETCONF access control model is be vigorously applied to
   prevent topology misconfiguration by unauthorized clients.

   Specifically, there

   There are a number of data nodes defined in these YANG
   module modules that
   are writable/creatable/deletable (i.e., config true, which is the
   default).  These data nodes may be considered sensitive or vulnerable
   in some network environments.  Write operations (e.g., edit-config)
   to these data nodes without proper protection can have a negative
   effect on network operations.  These are the subtrees and data nodes
   and their sensitivity/vulnerability in sensitivity/vulnerability:

   In the ietf-network "ietf-network" module:

   o  network: A malicious client could attempt to remove or add a
      network in an attempt effort to remove an overlay topology, topology or to create an
      unauthorized overlay.

   o  supporting-network:  supporting network: A malicious client could attempt to disrupt
      the logical structure of the model, resulting in a lack of overall
      data integrity and making it more difficult to, for example,
      troubleshoot problems rooted in the layering of network
      topologies.

   o  node: A malicious client could attempt to remove or add a node
      from network, the network -- for example example, in order to sabotage the topology
      of a network overlay.

   o  supporting-node:  supporting node: A malicious client could attempt to change the
      supporting-node
      supporting node in order to sabotage the layering of an overlay.

   These are the subtrees and data nodes and their sensitivity/
   vulnerability in

   In the ietf-network-topology "ietf-network-topology" module:

   o  link: A malicious client could attempt to remove a link from a
      topology, or add a new link, or manipulate the way the link is layered
      over supporting links, or modify the source or destination of the
      link.  Either way,  In each case, the structure of the topology would be
      sabotaged, which and this scenario could, for example, result in an
      overlay topology that is less than optimal.

   o  termination-point:  termination point: A malicious client could attempt to remove
      termination points from a node, or add "phantom" termination points
      to a node, or change the layering dependencies of termination
      points, again in an attempt effort to sabotage the integrity of a topology
      and potentially disrupt orderly operations of an overlay.

9.  Contributors

   The data model presented  References

9.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in this paper was contributed to by more
   people than can be listed on the author list.  Additional
   contributors include:

   o  Vishnu Pavan Beeram, Juniper

   o  Ken Gray, Cisco

   o  Tom Nadeau, Brocade

   o  Tony Tkacik

   o  Kent Watsen, Juniper

   o  Aleksandr Zhdankin, Cisco

10.  Acknowledgements

   We wish RFCs to acknowledge the helpful contributions, comments, and
   suggestions that were received from Alia Atlas, Andy Bierman, Martin
   Bjorklund, Igor Bryskin, Benoit Claise, Susan Hares, Ladislav Lhotka,
   Carlos Pignataro, Juergen Schoenwaelder, Robert Wilton, Qin Wu, and
   Xian Zhang.

11.  References

11.1.  Normative References

   [I-D.draft-ietf-netmod-revised-datastores]
              Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "A Revised Conceptual Model for YANG
              Datastores", I-D draft-ietf-netmod-revised-datastores-07,
              November 2017.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to indicate
              requirement levels", RFC 2119, March 1997.

   [RFC3688]  Mealling, M., "The IETF XML Registry", RFC 3688, January
              2004.

   [RFC5246]  Dierks, T. Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246,
              DOI 10.17487/RFC5246, August 2008. 2008,
              <https://www.rfc-editor.org/info/rfc5246>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010. 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011. 2011,
              <https://www.rfc-editor.org/info/rfc6241>.

   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011.

   [RFC6536]  Bierman, A. and M. Bjorklund, "Network Configuration
              Protocol (NETCONF) Access Control Model", RFC 6536, March
              2012. 2011,
              <https://www.rfc-editor.org/info/rfc6242>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013. 2013,
              <https://www.rfc-editor.org/info/rfc6991>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016. 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017. 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
              RFC 2119 Key Words", BCP 14, RFC 8174,
              DOI 10.17487/RFC8174, May 2017.

11.2.  Informative References

   [I-D.draft-ietf-i2rs-usecase-reqs-summary]
              Hares, S. and M. Chen, "Summary of I2RS Use Case
              Requirements", I-D draft-ietf-i2rs-usecase-reqs-summary-
              03, November 2016.

   [I-D.draft-ietf-i2rs-yang-l3-topology]
              Clemm, A., Medved, J., Varga, R., Liu, X.,
              Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model
              for Layer 3 Topologies", I-D draft-ietf-i2rs-yang-l3-
              topology-16, December 2017.

   [I-D.draft-ietf-netconf-yang-push]
              Clemm, A., Voit, E., Gonzalez Prieto, A., Tripathy, A.,
              Nilsen-Nygaard, E., 2017,
              <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8341]  Bierman, A., A. and B. Lengyel,
              "Subscribing to YANG datastore push updates", I-D draft-
              ietf-netconf-yang-push-11, October 2017.

   [I-D.draft-ietf-netmod-yang-tree-diagrams]
              Bjorklund, M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/info/rfc8341>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and L. Berger, "YANG Tree Diagrams", I-D
              draft-ietf-netmod-yang-tree-diagrams, October 2017. R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.

9.2.  Informative References

   [RFC1195]  Callon, R., "Use of OSI IS-IS for Routing routing in TCP/IP and
              Dual Environments",
              dual environments", RFC 1195, DOI 10.17487/RFC1195,
              December 1990. 1990, <https://www.rfc-editor.org/info/rfc1195>.

   [RFC2328]  Moy, J., "OSPF Version 2", STD 54, RFC 2328,
              DOI 10.17487/RFC2328, April 1998. 1998,
              <https://www.rfc-editor.org/info/rfc2328>.

   [RFC3209]  Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V.,
              and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP
              Tunnels", RFC 3209, DOI 10.17487/RFC3209, December 2001. 2001,
              <https://www.rfc-editor.org/info/rfc3209>.

   [RFC3444]  Pras, A. and J. Schoenwaelder, "On the Difference between
              Information Models and Data Models", RFC 3444,
              DOI 10.17487/RFC3444, January
              2003.

   [RFC7223]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 7223, May 2014. 2003,
              <https://www.rfc-editor.org/info/rfc3444>.

   [RFC7951]  Lhotka, L., "JSON Encoding of Data Modeled with YANG",
              RFC 7951, DOI 10.17487/RFC7951, August 2016. 2016,
              <https://www.rfc-editor.org/info/rfc7951>.

   [RFC7952]  Lhotka, L., "Defining and Using Metadata with YANG",
              RFC 7952, DOI 10.17487/RFC7952, August 2016. 2016,
              <https://www.rfc-editor.org/info/rfc7952>.

   [RFC8022]  Lhotka, L. and A. Lindem, "A YANG Data Model for Routing
              Management", RFC 8022, DOI 10.17487/RFC8022,
              November 2016. 2016, <https://www.rfc-editor.org/info/rfc8022>.

   [RFC8242]  Haas, J. and S. Hares, "I2RS "Interface to the Routing System
              (I2RS) Ephemeral State Requirements", RFC 8242,
              DOI 10.17487/RFC8242, September 2017. 2017,
              <https://www.rfc-editor.org/info/rfc8242>.

   [RFC8340]  Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
              BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
              <https://www.rfc-editor.org/info/rfc8340>.

   [RFC8343]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
              <https://www.rfc-editor.org/info/rfc8343>.

   [RFC8346]  Clemm, A., Medved, J., Varga, R., Liu, X.,
              Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model
              for Layer 3 Topologies", RFC 8346, DOI 10.17487/RFC8346,
              March 2018, <https://www.rfc-editor.org/info/rfc8346>.

   [USECASE-REQS]
              Hares, S. and M. Chen, "Summary of I2RS Use Case
              Requirements", Work in Progress, draft-ietf-i2rs-usecase-
              reqs-summary-03, November 2016.

   [YANG-Push]
              Clemm, A., Voit, E., Gonzalez Prieto, A., Tripathy, A.,
              Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, "YANG
              Datastore Subscription", Work in Progress, draft-ietf-
              netconf-yang-push-15, February 2018.

Appendix A.  Model Use Cases

A.1.  Fetching Topology from a Network Element

   In its simplest form, topology is learned by a network element (e.g.,
   a router) through its participation in peering protocols (IS-IS, BGP,
   etc.).  This learned topology can then be exported (e.g., to a
   Network Management System) for external utilization.  Typically, any
   network element in a domain can be queried for its topology and be
   expected to return the same result.

   In a slightly more complex form, the network element may be a
   controller, either by nature of it having
   controller.  It could be a network element with satellite or
   subtended devices hanging off of it, or it could be a controller in
   the more classical sense, such as sense -- that is, a special device designated to
   orchestrate the activities of a number of other devices (e.g., an optical controller).
   Optical Controller).  In this case, the controller device is
   logically a singleton and must be queried distinctly.

   It is worth noting that controllers can be built on top of other
   controllers to establish a topology incorporating of all of the domains
   within an entire network.

   In all of the cases above, the topology learned by the network
   element is considered to be operational state data.  That is, the
   data is accumulated purely by the network element's interactions with
   other systems and is subject to change dynamically without input or
   consent.

A.2.  Modifying TE Topology Imported from an Optical Controller

   Consider a scenario where an Optical Transport Controller presents its topology
   topology, in abstract TE Terms terms, to a Client Packet Controller. client packet controller.  This Customized Topology (that
   customized topology (which gets merged into the Client's client's native
   topology) contains sufficient information for the path computing path-computing
   client to select paths across the optical domain according to its
   policies.  If the Client client determines (at any given point in time) that
   this imported topology does not exactly cater exactly to its requirements, it
   may decide to request modifications to the topology.  Such
   customization requests may include the addition or deletion of
   topological elements or the modification of attributes associated
   with existing topological elements.  From the perspective of the
   Optical Controller, these requests translate into configuration
   changes to the exported abstract topology.

A.3.  Annotating Topology for Local Computation

   In certain scenarios, the topology learned by a controller needs to
   be augmented with additional attributes before running a computation
   algorithm on it.  Consider the case where a path-computation
   application on the controller needs to take the geographic
   coordinates of the nodes into account while computing paths on the
   learned topology.  If the learned topology does not contain these
   coordinates, then these additional attributes must be configured on
   the corresponding topological elements.

A.4.  SDN Controller-Based Configuration of Overlays on Top of Underlays

   In this scenario, an SDN controller Controller (for example, Open Daylight)
   maintains a view of the topology of the network that it controls
   based on information that it discovers from the network.  In
   addition, it provides an application in which it configures and
   maintains an overlay topology.

   The SDN Controller thus maintains two roles:

   o  It is a client to the network.

   o  It is a server to its own northbound applications and clients,
      e.g.
      e.g., an OSS. Operations Support System (OSS).

   In other words, one system's client (or controller, in this case) may
   be another system's server (or managed system).

   In this scenario, the SDN controller Controller maintains a consolidated data
   model of multiple layers of topology.  This includes the lower layers
   of the network topology, built from information that is discovered
   from the network.  It also includes upper layers of topology overlay,
   configurable by the controller's client, i.e. i.e., the OSS.  To the OSS,
   the lower topology layers constitute "read-only" information.  The
   upper topology layers need to be read-writable.

Appendix B.  Companion YANG models Data Models for non-NMDA compliant
             implementations Implementations Not
             Compliant with NMDA

   The YANG modules defined in this document are designed to be used in
   conjunction with implementations that support the Network Management
   Datastore Architecture (NMDA) as defined in
   [I-D.draft-ietf-netmod-revised-datastores]. [RFC8342].  In order to
   allow implementations to use the data model even in cases when NMDA
   is not supported, in the following two companion modules --
   "ietf-network-state" and "ietf-network-topology-state" -- are defined that
   defined; they represent the operational state of networks and network topologies.
   The modules, ietf-network-state and ietf-network-topology-state,
   mirror
   topologies, respectively.  These modules ietf-network mirror the "ietf-network"
   and ietf-network-topology defined earlier "ietf-network-topology" modules (defined in Sections 6.1 and 6.2
   of this document.  However, document); however, in the case of these modules, all data
   nodes are non-configurable.  They represent state that comes into
   being by either (1) learning topology information from the network, network or by
   (2) applying configuration from the mirrored modules.

   The companion modules, ietf-network-state "ietf-network-state" and ietf-network-topology-
   state, "ietf-network-topology-state" companion
   modules are redundant and SHOULD NOT be supported by implementations
   that support NMDA.  It is for this reason that the definitions are
   defined NMDA; therefore, we define these modules in an appendix.
   Appendices B.1 and B.2 (below) instead of the main body of this
   document.

   As the structure of both modules mirrors that of their underlying
   modules, the YANG tree is not depicted separately.

B.1.  YANG Model Module for Network State

   NOTE TO RFC EDITOR: Please change the date in the file name after the
   CODE BEGINS statement to the date of the publication when published.

<CODE BEGINS> file "ietf-network-state@2017-12-18.yang" "ietf-network-state@2018-02-26.yang"

module ietf-network-state {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-network-state";
  prefix nw-s;

  import ietf-network {
    prefix nw;
    reference
      "draft-ietf-i2rs-yang-network-topo-20
      NOTE TO RFC EDITOR: Please replace above reference to
      draft-ietf-i2rs-yang-network-topo-20 with RFC
      number when published (i.e. RFC xxxx).";
      "RFC 8345: A YANG Data Model for Network Topologies";
  }

  organization
    "IETF I2RS (Interface to the Routing System) Working Group";

  contact
    "WG Web:    <http://tools.ietf.org/wg/i2rs/>    <https://datatracker.ietf.org/wg/i2rs/>
     WG List:   <mailto:i2rs@ietf.org>

     Editor:    Alexander Clemm
                <mailto:ludwig@clemm.org>

     Editor:    Jan Medved
                <mailto:jmedved@cisco.com>

     Editor:    Robert Varga
                <mailto:robert.varga@pantheon.tech>

     Editor:    Nitin Bahadur
                <mailto:nitin_bahadur@yahoo.com>
     Editor:    Hariharan Ananthakrishnan
                <mailto:hari@packetdesign.com>

     Editor:    Xufeng Liu
                <mailto:Xufeng_Liu@jabil.com>";
                <mailto:xufeng.liu.ietf@gmail.com>";

  description
    "This module defines a common base data model for a collection
     of nodes in a network.  Node definitions are further used
     in network topologies and inventories.  It represents
     information that is either (1) is learned and automatically populated,
     populated or information that (2) results from applying configured netwok network information
     that has been configured per the ietf-network 'ietf-network' data model,
     mirroring the corresponding data nodes in this data model.

     The data model mirrors ietf-network, 'ietf-network' but contains only
     read-only state data.  The data model is not needed when the
     underlying implementation infrastructure supports the Network
     Management Datastore Architecture (NMDA).

     Copyright (c) 2017 2018 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 Simplified BSD License
     set forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (http://trustee.ietf.org/license-info).
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of
     draft-ietf-i2rs-yang-network-topo-20; RFC 8345;
     see the RFC itself for full legal notices.

     NOTE TO RFC EDITOR: Please replace above reference to
     draft-ietf-i2rs-yang-network-topo-20 with RFC
     number when published (i.e. RFC xxxx)."; notices.";

  revision 2017-12-18 2018-02-26 {
    description
      "Initial revision.
       NOTE TO RFC EDITOR:
       (1) Please replace the following reference
       to draft-ietf-i2rs-yang-network-topo-20 with
       RFC number when published (i.e. RFC xxxx).
       (2) Please replace the date in the revision statement with the
       date of the publication when published."; revision.";
    reference
      "draft-ietf-i2rs-yang-network-topo-20";
      "RFC 8345: A YANG Data Model for Network Topologies";
  }
  grouping network-ref {
    description
      "Contains the information necessary to reference a network, network --
       for example example, an underlay network.";
    leaf network-ref {
      type leafref {
        path "/nw-s:networks/nw-s:network/nw-s:network-id";
      require-instance false;
      }
      description
        "Used to reference a network, network -- for example example, an underlay
         network.";
    }
  }

  grouping node-ref {
    description
      "Contains the information necessary to reference a node.";
    leaf node-ref {
      type leafref {
        path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+
          "/../network-ref]/nw-s:node/nw-s:node-id";
        require-instance false;
      }
      description
        "Used to reference a node.
         Nodes are identified relative to the network they are
         contained in."; that
         contains them.";
    }
    uses network-ref;
  }
  container networks {
    config false;
    description
      "Serves as a top-level container for a list of networks.";
    list network {
      key "network-id";
      description
        "Describes a network.
         A network typically contains an inventory of nodes,
         topological information (augmented through the
         network-topology data model), as well as and layering information.";
      container network-types {
        description
          "Serves as an augmentation target.
           The network type is indicated through corresponding
           presence containers augmented into this container.";
      }
      leaf network-id {
        type nw:network-id;
        description
          "Identifies a network.";
      }
      list supporting-network {
        key "network-ref";
        description
          "An underlay network, used to represent layered network
           topologies.";
        leaf network-ref {
          type leafref {
            path "/nw-s:networks/nw-s:network/nw-s:network-id";
          require-instance false;
          }
          description
            "References the underlay network.";
        }
      }
      list node {
        key "node-id";
        description
          "The inventory of nodes of this network.";
        leaf node-id {
          type nw:node-id;
          description
            "Identifies
            "Uniquely identifies a node uniquely within the containing
             network.";
        }
        list supporting-node {
          key "network-ref node-ref";
          description
            "Represents another node, node that is in an underlay network, network
             and that supports this node is supported by. node.  Used to represent layering
             structure.";
          leaf network-ref {
            type leafref {
              path "../../../nw-s:supporting-network/nw-s:network-ref";
            require-instance false;
            }
            description
              "References the underlay network that of which the
               underlay node is part of."; a part.";
          }
          leaf node-ref {
            type leafref {
              path "/nw-s:networks/nw-s:network/nw-s:node/nw-s:node-id";
            require-instance false;
            }
            description
              "References the underlay node itself.";
          }
        }
      }
    }
  }
}

<CODE ENDS>

B.2.  YANG Data Model Module for Network Topology State

   NOTE TO RFC EDITOR: Please change the date in the file name after the
   CODE BEGINS statement to the date of the publication when published.

  <CODE BEGINS> file "ietf-network-topology-state@2017-12-18.yang" "ietf-network-topology-state@2018-02-26.yang"

  module ietf-network-topology-state {
    yang-version 1.1;
    namespace "urn:ietf:params:xml:ns:yang:ietf-network-topology-state";
    prefix nt-s;

    import ietf-network-state {
      prefix nw-s;
      reference
        "draft-ietf-i2rs-yang-network-topo-20
        NOTE TO RFC EDITOR: Please replace above reference to
        draft-ietf-i2rs-yang-network-topo-20 with RFC
        number when published (i.e. RFC xxxx)."; ietf-network-state {
      prefix nw-s;
      reference
        "RFC 8345: A YANG Data Model for Network Topologies";
    }
    import ietf-network-topology {
      prefix nt;
      reference
        "draft-ietf-i2rs-yang-network-topo-20
        NOTE TO RFC EDITOR: Please replace above reference to
        draft-ietf-i2rs-yang-network-topo-20 with RFC
        number when published (i.e. RFC xxxx).";
        "RFC 8345: A YANG Data Model for Network Topologies";
    }

    organization
      "IETF I2RS (Interface to the Routing System) Working Group";

    contact
      "WG Web:    <http://tools.ietf.org/wg/i2rs/>    <https://datatracker.ietf.org/wg/i2rs/>
       WG List:   <mailto:i2rs@ietf.org>

       Editor:    Alexander Clemm
                  <mailto:ludwig@clemm.org>

       Editor:    Jan Medved
                  <mailto:jmedved@cisco.com>

       Editor:    Robert Varga
                  <mailto:robert.varga@pantheon.tech>

       Editor:    Nitin Bahadur
                  <mailto:nitin_bahadur@yahoo.com>

       Editor:    Hariharan Ananthakrishnan
                  <mailto:hari@packetdesign.com>

       Editor:    Xufeng Liu
                  <mailto:Xufeng_Liu@jabil.com>";
                  <mailto:xufeng.liu.ietf@gmail.com>";
    description
      "This module defines a common base data model for network
       topology state, representing topology that is either learned, (1) is learned
       or topology that (2) results from applying topology that has been configured
       per the ietf-network-topology 'ietf-network-topology' data model, mirroring the
       corresponding data nodes in this data model.  It augments the
       base network state data model with links to connect nodes, as
       well as termination points to terminate links on nodes.

       The data model mirrors ietf-network-topology, 'ietf-network-topology' but contains only
       read-only state data.  The data model is not needed when the
       underlying implementation infrastructure supports the Network
       Management Datastore Architecture (NMDA).

       Copyright (c) 2017 2018 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 Simplified BSD License
       set forth in Section 4.c of the IETF Trust's Legal Provisions
       Relating to IETF Documents
       (http://trustee.ietf.org/license-info).
       (https://trustee.ietf.org/license-info).

       This version of this YANG module is part of
       draft-ietf-i2rs-yang-network-topo-20; RFC 8345;
       see the RFC itself for full legal notices.

       NOTE TO RFC EDITOR: Please replace above reference to
       draft-ietf-i2rs-yang-network-topo-20 with RFC
       number when published (i.e. RFC xxxx)."; notices.";

    revision 2017-12-18 2018-02-26 {
      description
        "Initial revision.
         NOTE TO RFC EDITOR:
         (1) Please replace the following reference
         to draft-ietf-i2rs-yang-network-topo-20 with
         RFC number when published (i.e. RFC xxxx).
         (2) Please replace the date in the revision statement with the
         date of publication when published."; revision.";
      reference
        "draft-ietf-i2rs-yang-network-topo-20";
        "RFC 8345: A YANG Data Model for Network Topologies";
    }
    grouping link-ref {
      description
        "References a link in a specific network.  While  Although this
         grouping is not used in this module, it is defined here for
         the convenience of augmenting modules.";
      leaf link-ref {
        type leafref {
          path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+
            "/../network-ref]/nt-s:link/nt-s:link-id";
          require-instance false;
        }
        description
          "A type for an absolute reference to a link instance.
           (This type should not be used for relative references.
           In such a case, a relative path should be used instead.)";
      }
      uses nw-s:network-ref;
    }

    grouping tp-ref {
      description
        "References a termination point in a specific node.  While  Although
         this grouping is not used in this module, it is defined here
         for the convenience of augmenting modules.";
      leaf tp-ref {
        type leafref {
          path "/nw-s:networks/nw-s:network[nw-s:network-id=current()"+
            "/../network-ref]/nw-s:node[nw-s:node-id=current()/../"+
            "node-ref]/nt-s:termination-point/nt-s:tp-id";
          require-instance false;
        }
        description
          "A type for an absolute reference to a termination point.
           (This type should not be used for relative references.
           In such a case, a relative path should be used instead.)";
      }
      uses nw-s:node-ref;
    }

    augment "/nw-s:networks/nw-s:network" {
      description
        "Add links to the network data model.";
      list link {
        key "link-id";
        description
          "A network link connects a local (source) node and
           a remote (destination) node via a set of the respective
           node's termination points.  It is possible to have several
           links between the same source and destination nodes.
           Likewise, a link could potentially be re-homed between
           termination points.  Therefore, in order to ensure that we
           would always know to distinguish between links, every link
           is identified by a dedicated link identifier.  Note that a
           link models a point-to-point link, not a multipoint link.";
        container source {
          description
            "This container holds the logical source of a particular
             link.";
          leaf source-node {
            type leafref {
              path "../../../nw-s:node/nw-s:node-id";
              require-instance false;
            }
            description
              "Source node identifier, must identifier.  Must be in the same topology.";
          }
          leaf source-tp {
            type leafref {
              path "../../../nw-s:node[nw-s:node-id=current()/../"+
                "source-node]/termination-point/tp-id";
              require-instance false;
            }
            description
              "Termination
              "This termination point is located within the source node that
               and terminates the link.";
          }
        }
        container destination {
          description
            "This container holds the logical destination of a
             particular link.";
          leaf dest-node {
            type leafref {
              path "../../../nw-s:node/nw-s:node-id";
            require-instance false;
            }
            description
              "Destination node identifier, must identifier.  Must be in the same
               network.";
          }
          leaf dest-tp {
            type leafref {
              path "../../../nw-s:node[nw-s:node-id=current()/../"+
                "dest-node]/termination-point/tp-id";
              require-instance false;
            }
            description
              "Termination
              "This termination point is located within the
               destination node that and terminates the link.";
          }
        }
        leaf link-id {
          type nt:link-id;
          description
            "The identifier of a link in the topology.
             A link is specific to a topology to which it belongs.";
        }
        list supporting-link {
          key "network-ref link-ref";
          description
            "Identifies the link, link or links, that links on which this link
             is dependent on."; depends.";
          leaf network-ref {
            type leafref {
              path "../../../nw-s:supporting-network/nw-s:network-ref";
            require-instance false;
            }
            description
              "This leaf identifies in which underlay topology
               the supporting link is present.";
          }
          leaf link-ref {
            type leafref {
              path "/nw-s:networks/nw-s:network[nw-s:network-id="+
                "current()/../network-ref]/link/link-id";
              require-instance false;
            }
            description
              "This leaf identifies a link which that is a part
               of this link's underlay.  Reference loops in which
               a link identifies itself as its underlay, either
               directly or transitively, are not allowed.";
          }
        }
      }
    }
    augment "/nw-s:networks/nw-s:network/nw-s:node" {
      description
        "Augment
        "Augments termination points which that terminate links.
         Termination points can ultimately be mapped to interfaces.";
      list termination-point {
        key "tp-id";
        description
          "A termination point can terminate a link.
           Depending on the type of topology, a termination point
           could, for example, refer to a port or an interface.";
        leaf tp-id {
          type nt:tp-id;
          description
            "Termination point identifier.";
        }
        list supporting-termination-point {
          key "network-ref node-ref tp-ref";
          description
            "This list identifies any termination points that
             the on which a
             given termination point is dependent on, depends or maps onto. onto which it maps.
             Those termination points will themselves be contained
             in a supporting node.  This dependency information can be
             inferred from the dependencies between links.  For this reason,  Therefore,
             this item is not separately configurable.  Hence  Hence, no
             corresponding constraint needs to be articulated.
             The corresponding information is simply provided by the
             implementing system.";
          leaf network-ref {
            type leafref {
              path "../../../nw-s:supporting-node/nw-s:network-ref";
            require-instance false;
            }
            description
              "This leaf identifies in which topology the
               supporting termination point is present.";
          }
          leaf node-ref {
            type leafref {
              path "../../../nw-s:supporting-node/nw-s:node-ref";
            require-instance false;
            }
            description
              "This leaf identifies in which node the supporting
               termination point is present.";
          }
          leaf tp-ref {
            type leafref {
              path "/nw-s:networks/nw-s:network[nw-s:network-id="+
                "current()/../network-ref]/nw-s:node[nw-s:node-id="+
                "current()/../node-ref]/termination-point/tp-id";
              require-instance false;
            }
            description
              "Reference to the underlay node, node (the underlay node must
               be in a different topology"; topology).";
          }
        }
      }
    }
  }

  <CODE ENDS>

Appendix C.  An Example

   This section contains an example of an instance data tree in JSON
   encoding [RFC7951].  The example instantiates ietf-network-topology "ietf-network-topology"
   (and ietf-network, "ietf-network", which ietf-network-topology "ietf-network-topology" augments) for the
   topology that is depicted in the following diagram. Figure 7.  There are three
   nodes, nodes: D1, D2, and
   D3.  D1 has three termination points, 1-0-1, points (1-0-1, 1-2-1, and 1-3-1. 1-3-1).
   D2 has three termination points as well, 2-1-1, well (2-1-1, 2-0-1, and 2-3-1. 2-3-1).
   D3 has two termination points, 3-1-1 points (3-1-1 and 3-2-1. 3-2-1).  In addition addition, there
   are six links, two between each pair of nodes with one going in each
   direction.

                +------------+                   +------------+
                |     D1     |                   |     D2     |
               /-\          /-\                 /-\          /-\
               | | 1-0-1    | |---------------->| | 2-1-1    | |
               | |    1-2-1 | |<----------------| |    2-0-1 | |
               \-/  1-3-1   \-/                 \-/  2-3-1   \-/
                |   /----\   |                   |   /----\   |
                +---|    |---+                   +---|    |---+
                    \----/                           \----/
                     A  |                             A  |
                     |  |                             |  |
                     |  |                             |  |
                     |  |       +------------+        |  |
                     |  |       |     D3     |        |  |
                     |  |      /-\          /-\       |  |
                     |  +----->| | 3-1-1    | |-------+  |
                     +---------| |    3-2-1 | |<---------+
                               \-/          \-/
                                |            |
                                +------------+

                   Figure 7: A network topology example Network Topology Example
   The corresponding instance data tree is depicted below: in Figure 8:

   {
     "ietf-network:networks": {
       "network": [
         {
           "network-types": {
           },
           "network-id": "otn-hc",
           "node": [
             {
               "node-id": "D1",
               "termination-point": [
                 {
                   "tp-id": "1-0-1"
                 },
                 {
                   "tp-id": "1-2-1"
                 },
                 {
                   "tp-id": "1-3-1"
                 }
               ]
             },
             {
               "node-id": "D2",
               "termination-point": [
                 {
                   "tp-id": "2-0-1"
                 },
                 {
                   "tp-id": "2-1-1"
                 },
                 {
                   "tp-id": "2-3-1"
                 }
               ]
             },
             {
               "node-id": "D3",
               "termination-point": [
                 {
                   "tp-id": "3-1-1"
                 },
                 {
                   "tp-id": "3-2-1"
                 }
               ]
             }
           ],
           "ietf-network-topology:link": [
             {
               "link-id": "D1,1-2-1,D2,2-1-1",
               "destination":
               "source": {
                 "source-node": "D1",
                 "source-tp": "1-2-1"
               }
               "destination": {
                 "dest-node": "D2",
                 "dest-tp": "2-1-1"
               }
             },
             {
               "link-id": "D2,2-1-1,D1,1-2-1",
               "destination":
               "source": {
                 "source-node": "D2",
                 "source-tp": "2-1-1"
               }
               "destination": {
                 "dest-node": "D1",
                 "dest-tp": "1-2-1"
               }
             },
             {
               "link-id": "D1,1-3-1,D3,3-1-1",
               "destination":
               "source": {
                 "source-node": "D1",
                 "source-tp": "1-3-1"
               }
               "destination": {
                 "dest-node": "D3",
                 "dest-tp": "3-1-1"
               }
             },
             {
               "link-id": "D3,3-1-1,D1,1-3-1",
               "destination":
               "source": {
                 "source-node": "D3",
                 "source-tp": "3-1-1"
               }
               "destination": {
                 "dest-node": "D1",
                 "dest-tp": "1-3-1"
               }
             },
             {
               "link-id": "D2,2-3-1,D3,3-2-1",
               "destination":
               "source": {
                 "source-node": "D2",
                 "source-tp": "2-3-1"
               }
               "destination": {
                 "dest-node": "D3",
                 "dest-tp": "3-2-1"
               }
             },
             {
               "link-id": "D3,3-2-1,D2,2-3-1",
               "destination":
               "source": {
                 "source-node": "D3",
                 "source-tp": "3-2-1"
               }
               "destination": {
                 "dest-node": "D2",
                 "dest-tp": "2-3-1"
               }
             }
           ]
         }
       ]
     }
   }

                       Figure 8: Instance Data Tree

Acknowledgments

   We wish to acknowledge the helpful contributions, comments, and
   suggestions that were received from Alia Atlas, Andy Bierman, Martin
   Bjorklund, Igor Bryskin, Benoit Claise, Susan Hares, Ladislav Lhotka,
   Carlos Pignataro, Juergen Schoenwaelder, Robert Wilton, Qin Wu, and
   Xian Zhang.

Contributors

   More people contributed to the data tree model presented in this paper
   than can be listed in the "Authors' Addresses" section.  Additional
   contributors include:

   o  Vishnu Pavan Beeram, Juniper

   o  Ken Gray, Cisco

   o  Tom Nadeau, Brocade

   o  Tony Tkacik

   o  Kent Watsen, Juniper

   o  Aleksandr Zhdankin, Cisco

Authors' Addresses

   Alexander Clemm
   Huawei

   EMail: ludwig@clemm.org USA - Futurewei Technologies Inc.
   Santa Clara, CA
   United States of America

   Email: ludwig@clemm.org, alexander.clemm@huawei.com

   Jan Medved
   Cisco

   EMail:

   Email: jmedved@cisco.com

   Robert Varga
   Pantheon Technologies SRO

   EMail:

   Email: robert.varga@pantheon.tech

   Nitin Bahadur
   Bracket Computing

   EMail:

   Email: nitin_bahadur@yahoo.com

   Hariharan Ananthakrishnan
   Packet Design

   EMail:

   Email: hari@packetdesign.com

   Xufeng Liu
   Jabil

   EMail: Xufeng_Liu@jabil.com

   Email: xufeng.liu.ietf@gmail.com