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

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