code-generator/maven-sal-api-gen-plugin/src/test/resources/doc-gen/network-topology@2013-07-12.yang

   1 module network-topology  {
   2     yang-version 1;
   3     namespace "urn:TBD:params:xml:ns:yang:network-topology";
   4     // replace with IANA namespace when assigned
   5     prefix "nt";
   6
   7     organization "TBD";
   8
   9     contact "WILL-BE-DEFINED-LATER";
  10 /*
  11     description
  12         "This module defines a model for the topology of a network.
  13         Key design decisions are as follows:
  14         A topology consists of a set of nodes and links.
  15         Links are point-to-point and unidirectional.
  16         Bidirectional connections need to be represented through
  17         two separate links.
  18         Multipoint connections, broadcast domains etc can be represented
  19         through a hierarchy of nodes, then connecting nodes at
  20         upper layers of the hierarchy.";
  21 */
  22     revision 2013-07-12 {
  23         description
  24             "Initial revision.";
  25     }
  26
  27     typedef topology-id {
  28         type string;
  29         description
  30             "An identifier for a topology.";
  31     }
  32
  33     typedef node-id {
  34         type string;
  35         description
  36             "An identifier for a node in a topology.
  37             The identifier may be opaque.
  38             The identifier SHOULD be chosen such that the same node in a
  39             real network topology will always be identified through the
  40             same identifier, even if the model is instantiated in separate
  41             datastores. An implementation MAY choose to capture semantics
  42             in the identifier, for example to indicate the type of node
  43             and/or the type of topology that the node is a part of.";
  44     }
  45
  46     typedef link-id {
  47         type string;
  48         description
  49             "An identifier for a link in a topology.
  50             The identifier may be opaque.
  51             The identifier SHOULD be chosen such that the same link in a
  52             real network topology will always be identified through the
  53             same identifier, even if the model is instantiated in separate
  54             datastores. An implementation MAY choose to capture semantics
  55             in the identifier, for example to indicate the type of link
  56             and/or the type of topology that the link is a part of.";
  57     }
  58
  59     typedef tp-id {
  60         type string;
  61         description
  62             "An identifier for termination points on a node.
  63             The identifier may be opaque.
  64             The identifier SHOULD be chosen such that the same TP in a
  65             real network topology will always be identified through the
  66             same identifier, even if the model is instantiated in separate
  67             datastores. An implementation MAY choose to capture semantics
  68             in the identifier, for example to indicate the type of TP
  69             and/or the type of node and topology that the TP is a part of.";
  70     }
  71
  72     typedef tp-ref {
  73         type leafref {
  74             path "/network-topology/topology/node/termination-point/tp-id";
  75         }
  76         description
  77             "A type for an absolute reference to a termination point.
  78             (This type should not be used for relative references.
  79             In such a case, a relative path should be used instead.)";
  80     }
  81     typedef topology-ref {
  82         type leafref {
  83             path "/network-topology/topology/topology-id";
  84         }
  85         description
  86             "A type for an absolute reference a topology instance.";
  87     }
  88
  89     typedef node-ref {
  90         type leafref {
  91             path "/network-topology/topology/node/node-id";
  92         }
  93         description
  94             "A type for an absolute reference to a node instance.
  95             (This type should not be used for relative references.
  96             In such a case, a relative path should be used instead.)";
  97     }
  98
  99     typedef link-ref {
 100         type leafref {
 101             path "/network-topology/topology/link/link-id";
 102         }
 103         description
 104             "A type for an absolute reference a link instance.
 105             (This type should not be used for relative references.
 106             In such a case, a relative path should be used instead.)";
 107     }
 108
 109     typedef x {
 110         type binary {
 111             length 5..10;
 112         }
 113     }
 114
 115     typedef y {
 116         type int32 {
 117             range 5..555;
 118         }
 119     }
 120
 121     grouping tp-attributes {
 122         description
 123             "The data objects needed to define a termination point.
 124             (This only includes a single leaf at this point, used
 125             to identify the termination point.)
 126             Provided in a grouping so that in addition to the datastore,
 127             the data can also be included in notifications.";
 128         leaf tp-id {
 129             type tp-id;
 130         }
 131         leaf-list tp-ref {
 132             type tp-ref;
 133             config false;
 134             description
 135                 "The leaf list identifies any termination points that the
 136                 termination point is dependent on, or maps onto.
 137                 Those termination points will themselves be contained
 138                 in a supporting node.
 139                 This dependency information can be inferred from
 140                 the dependencies between links.  For this reason,
 141                 this item is not separately configurable.  Hence no
 142                 corresponding constraint needs to be articulated.
 143                 The corresponding information is simply provided by the
 144                 implementing system.";
 145         }
 146     }
 147
 148     grouping node-attributes {
 149         description
 150             "The data objects needed to define a node.
 151             The objects are provided in a grouping so that in addition to
 152             the datastore, the data can also be included in notifications
 153             as needed.";
 154         leaf node-id {
 155             type node-id;
 156             description
 157                 "The identifier of a node in the topology.
 158                 A node is specific to a topology to which it belongs.";
 159         }
 160         list supporting-node {
 161             description
 162                 "This list defines vertical layering information for nodes.
 163                 It allows to capture for any given node, which node (or nodes)
 164                 in the corresponding underlay topology it maps onto.
 165                 A node can map to zero, one, or more nodes below it;
 166                 accordingly there can be zero, one, or more elements in the list.
 167                 If there are specific layering requirements, for example
 168                 specific to a particular type of topology that only allows
 169                 for certain layering relationships, the choice
 170                 below can be augmented with additional cases.
 171                 A list has been chosen rather than a leaf-list in order
 172                 to provide room for augmentations, e.g. for
 173                 statistics or priorization information associated with
 174                 supporting nodes.";
 175             key "node-ref";
 176             leaf node-ref {
 177                 type node-ref;
 178             }
 179         }
 180     }
 181
 182     grouping link-attributes {
 183         // This is a grouping, not defined inline with the link definition itself,
 184         // so it can be included in a notification, if needed
 185         leaf link-id {
 186             type link-id;
 187             description
 188                 "The identifier of a link in the topology.
 189                 A link is specific to a topology to which it belongs.";
 190         }
 191         container source {
 192             description "XYZ";
 193             leaf source-node {
 194                 mandatory true;
 195                 type node-ref;
 196                 description
 197                     "Source node identifier, must be in same topology.";
 198             }
 199             leaf source-tp {
 200                 type tp-ref;
 201                 description
 202                     "Termination point within source node that terminates the link.";
 203             }
 204         }
 205         container destination {
 206             leaf dest-node {
 207                 mandatory true;
 208                 type node-ref;
 209                 description
 210                     "Destination node identifier, must be in same topology.";
 211             }
 212             leaf dest-tp {
 213                 type tp-ref;
 214                 description
 215                     "Termination point within destination node that terminates the link.";
 216             }
 217         }
 218         list supporting-link {
 219             key "link-ref";
 220             leaf link-ref {
 221                 type link-ref;
 222             }
 223         }
 224     }
 225
 226
 227     container network-topology {
 228         list topology {
 229             description "
 230                 This is the model of an abstract topology.
 231                 A topology contins nodes and links.
 232                 Each topology MUST be identified by
 233                 unique topology-id for reason that a network could contain many
 234                 topologies.
 235             ";
 236             key "topology-id";
 237             leaf topology-id {
 238                 type topology-id;
 239                 description "
 240                     It is presumed that a datastore will contain many topologies. To
 241                     distinguish between topologies it is vital to have UNIQUE
 242                     topology identifiers.
 243                 ";
 244             }
 245             container topology-types {
 246                 description
 247                     "This container is used to identify the type, or types
 248                     (as a topology can support several types simultaneously),
 249                     of the topology.
 250                     Topology types are the subject of several integrity constraints
 251                     that an implementing server can validate in order to
 252                     maintain integrity of the datastore.
 253                     Topology types are indicated through separate data nodes;
 254                     the set of topology types is expected to increase over time.
 255                     To add support for a new topology, an augmenting module
 256                     needs to augment this container with a new empty optional
 257                     container to indicate the new topology type.
 258                     The use of a container allows to indicate a subcategorization
 259                     of topology types.
 260                     The container SHALL NOT be augmented with any data nodes
 261                     that serve a purpose other than identifying a particular
 262                     topology type.
 263                 ";
 264             }
 265             list underlay-topology {
 266                 key "topology-ref";
 267                 leaf topology-ref {
 268                     type topology-ref;
 269                 }
 270                 // a list, not a leaf-list, to allow for potential augmentation
 271                 // with properties specific to the underlay topology,
 272                 // such as statistics, preferences, or cost.
 273                 description
 274                     "Identifies the topology, or topologies, that this topology
 275                     is dependent on.";
 276             }
 277
 278             list node {
 279                 description "The list of network nodes defined for the topology.";
 280                 key "node-id";
 281                 uses node-attributes;
 282                 must "boolean(../underlay-topology[*]/node[./supporting-nodes/node-ref])";
 283                     // This constraint is meant to ensure that a referenced node is in fact
 284                     // a node in an underlay topology.
 285                 list termination-point {
 286                     description
 287                         "A termination point can terminate a link.
 288                         Depending on the type of topology, a termination point could,
 289                         for example, refer to a port or an interface.";
 290                     key "tp-id";
 291                     uses tp-attributes;
 292                 }
 293             }
 294
 295             list link {
 296                 description "
 297                     A Network Link connects a by Local (Source) node and
 298                     a Remote (Destination) Network Nodes via a set of the
 299                     nodes' termination points.
 300                     As it is possible to have several links between the same
 301                     source and destination nodes, and as a link could potentially
 302                     be re-homed between termination points, to ensure that we
 303                     would always know to distinguish between links, every link
 304                     is identified by a dedicated link identifier.
 305                     Note that a link models a point-to-point link, not a multipoint
 306                     link.
 307                     Layering dependencies on links in underlay topologies are
 308                     not represented as the layering information of nodes and of
 309                     termination points is sufficient.
 310                 ";
 311                 key "link-id";
 312                 uses link-attributes;
 313                 must "boolean(../underlay-topology/link[./supporting-link]";
 314                     // Constraint: any supporting link must be part of an underlay topology
 315                 must "boolean(../node[./source/source-node])";
 316                     // Constraint: A link must have as source a node of the same topology
 317                 must "boolean(../node[./destination/dest-node])";
 318                     // Constraint: A link must have as source a destination of the same topology
 319                 must "boolean(../node/termination-point[./source/source-tp])";
 320                     // Constraint: The source termination point must be contained in the source node
 321                 must "boolean(../node/termination-point[./destination/dest-tp])";
 322                     // Constraint: The destination termination point must be contained
 323                     // in the destination node
 324             }
 325         }
 326     }
 327
 328     notification n1 {
 329         description "This example defines a notification 1.";
 330         leaf event-class {
 331             type string;
 332         }
 333         anyxml reporting-entity;
 334         container severity {
 335             leaf id {
 336                 type string;
 337             }
 338         }
 339     }
 340
 341     notification n2 {
 342         description "This example defines a notification 2.";
 343         leaf event-class {
 344             type string;
 345         }
 346         anyxml reporting-entity;
 347         leaf severity {
 348             type string;
 349         }
 350     }
 351
 352     augment "/network-topology" {
 353         anyxml any-a;
 354         anyxml any-b;
 355     }
 356
 357     augment "/network-topology/topology" {
 358         description "description of augment 2";
 359         reference "reference of augment 2";
 360         list list-a {}
 361         list list-b {
 362             leaf leaf-c {
 363                 type string;
 364             }
 365         }
 366     }
 367
 368     augment "/network-topology/topology/topology-types" {
 369         container container-c {
 370             leaf id {
 371                 type binary;
 372             }
 373         }
 374     }
 375
 376     rpc rock-the-house {
 377         input {
 378             leaf zip-code {
 379                 type string;
 380             }
 381         }
 382         output {
 383             leaf number {
 384                 type int32;
 385             }
 386         }
 387     }
 388
 389     extension c-define {
 390         description
 391             "Takes as argument a name string.
 392             Makes the code generator use the given name in the
 393             #define.";
 394         argument "name";
 395     }
 396
 397 }