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|15..20|25..30;
 112         }
 113         description "x type description";
 114         reference "x type reference";
 115     }
 116
 117     typedef y {
 118         type int32 {
 119             range 5..555;
 120         }
 121     }
 122
 123     identity crypto-alg {
 124         description "Base identity from which all crypto algorithms are derived.";
 125     }
 126
 127     identity des {
 128         base "crypto-alg";
 129         description "DES crypto algorithm";
 130     }
 131
 132     identity des3 {
 133         base "crypto-alg";
 134         description "Triple DES crypto algorithm";
 135     }
 136
 137     grouping tp-attributes {
 138         description
 139             "The data objects needed to define a termination point.
 140             (This only includes a single leaf at this point, used
 141             to identify the termination point.)
 142             Provided in a grouping so that in addition to the datastore,
 143             the data can also be included in notifications.";
 144         leaf tp-id {
 145             type tp-id;
 146         }
 147         leaf-list tp-ref {
 148             type tp-ref;
 149             config false;
 150             description
 151                 "The leaf list identifies any termination points that the
 152                 termination point is dependent on, or maps onto.
 153                 Those termination points will themselves be contained
 154                 in a supporting node.
 155                 This dependency information can be inferred from
 156                 the dependencies between links.  For this reason,
 157                 this item is not separately configurable.  Hence no
 158                 corresponding constraint needs to be articulated.
 159                 The corresponding information is simply provided by the
 160                 implementing system.";
 161         }
 162     }
 163
 164     grouping node-attributes {
 165         description
 166             "The data objects needed to define a node.
 167             The objects are provided in a grouping so that in addition to
 168             the datastore, the data can also be included in notifications
 169             as needed.";
 170         leaf node-id {
 171             type node-id;
 172             description
 173                 "The identifier of a node in the topology.
 174                 A node is specific to a topology to which it belongs.";
 175         }
 176         list supporting-node {
 177             description
 178                 "This list defines vertical layering information for nodes.
 179                 It allows to capture for any given node, which node (or nodes)
 180                 in the corresponding underlay topology it maps onto.
 181                 A node can map to zero, one, or more nodes below it;
 182                 accordingly there can be zero, one, or more elements in the list.
 183                 If there are specific layering requirements, for example
 184                 specific to a particular type of topology that only allows
 185                 for certain layering relationships, the choice
 186                 below can be augmented with additional cases.
 187                 A list has been chosen rather than a leaf-list in order
 188                 to provide room for augmentations, e.g. for
 189                 statistics or priorization information associated with
 190                 supporting nodes.";
 191             key "node-ref";
 192             leaf node-ref {
 193                 type node-ref;
 194             }
 195         }
 196     }
 197
 198     grouping link-attributes {
 199         // This is a grouping, not defined inline with the link definition itself,
 200         // so it can be included in a notification, if needed
 201         leaf link-id {
 202             type link-id;
 203             description
 204                 "The identifier of a link in the topology.
 205                 A link is specific to a topology to which it belongs.";
 206         }
 207         container source {
 208             description "XYZ";
 209             leaf source-node {
 210                 mandatory true;
 211                 type node-ref;
 212                 description
 213                     "Source node identifier, must be in same topology.";
 214             }
 215             leaf source-tp {
 216                 type tp-ref;
 217                 description
 218                     "Termination point within source node that terminates the link.";
 219             }
 220         }
 221         container destination {
 222             leaf dest-node {
 223                 mandatory true;
 224                 type node-ref;
 225                 description
 226                     "Destination node identifier, must be in same topology.";
 227             }
 228             leaf dest-tp {
 229                 type tp-ref;
 230                 description
 231                     "Termination point within destination node that terminates the link.";
 232             }
 233         }
 234         list supporting-link {
 235             key "link-ref";
 236             leaf link-ref {
 237                 type link-ref;
 238             }
 239         }
 240     }
 241
 242
 243     container network-topology {
 244         list topology {
 245             description "
 246                 This is the model of an abstract topology.
 247                 A topology contins nodes and links.
 248                 Each topology MUST be identified by
 249                 unique topology-id for reason that a network could contain many
 250                 topologies.
 251             ";
 252             key "topology-id";
 253             leaf topology-id {
 254                 type topology-id;
 255                 description "
 256                     It is presumed that a datastore will contain many topologies. To
 257                     distinguish between topologies it is vital to have UNIQUE
 258                     topology identifiers.
 259                 ";
 260             }
 261             container topology-types {
 262                 description
 263                     "This container is used to identify the type, or types
 264                     (as a topology can support several types simultaneously),
 265                     of the topology.
 266                     Topology types are the subject of several integrity constraints
 267                     that an implementing server can validate in order to
 268                     maintain integrity of the datastore.
 269                     Topology types are indicated through separate data nodes;
 270                     the set of topology types is expected to increase over time.
 271                     To add support for a new topology, an augmenting module
 272                     needs to augment this container with a new empty optional
 273                     container to indicate the new topology type.
 274                     The use of a container allows to indicate a subcategorization
 275                     of topology types.
 276                     The container SHALL NOT be augmented with any data nodes
 277                     that serve a purpose other than identifying a particular
 278                     topology type.
 279                 ";
 280             }
 281             list underlay-topology {
 282                 key "topology-ref";
 283                 leaf topology-ref {
 284                     type topology-ref;
 285                 }
 286                 // a list, not a leaf-list, to allow for potential augmentation
 287                 // with properties specific to the underlay topology,
 288                 // such as statistics, preferences, or cost.
 289                 description
 290                     "Identifies the topology, or topologies, that this topology
 291                     is dependent on.";
 292             }
 293
 294             list node {
 295                 description "The list of network nodes defined for the topology.";
 296                 key "node-id";
 297                 uses node-attributes;
 298                 must "boolean(../underlay-topology[*]/node[./supporting-nodes/node-ref])";
 299                     // This constraint is meant to ensure that a referenced node is in fact
 300                     // a node in an underlay topology.
 301                 list termination-point {
 302                     description
 303                         "A termination point can terminate a link.
 304                         Depending on the type of topology, a termination point could,
 305                         for example, refer to a port or an interface.";
 306                     key "tp-id";
 307                     uses tp-attributes;
 308                 }
 309             }
 310
 311             list link {
 312                 description "
 313                     A Network Link connects a by Local (Source) node and
 314                     a Remote (Destination) Network Nodes via a set of the
 315                     nodes' termination points.
 316                     As it is possible to have several links between the same
 317                     source and destination nodes, and as a link could potentially
 318                     be re-homed between termination points, to ensure that we
 319                     would always know to distinguish between links, every link
 320                     is identified by a dedicated link identifier.
 321                     Note that a link models a point-to-point link, not a multipoint
 322                     link.
 323                     Layering dependencies on links in underlay topologies are
 324                     not represented as the layering information of nodes and of
 325                     termination points is sufficient.
 326                 ";
 327                 key "link-id";
 328                 uses link-attributes;
 329                 must "boolean(../underlay-topology/link[./supporting-link]";
 330                     // Constraint: any supporting link must be part of an underlay topology
 331                 must "boolean(../node[./source/source-node])";
 332                     // Constraint: A link must have as source a node of the same topology
 333                 must "boolean(../node[./destination/dest-node])";
 334                     // Constraint: A link must have as source a destination of the same topology
 335                 must "boolean(../node/termination-point[./source/source-tp])";
 336                     // Constraint: The source termination point must be contained in the source node
 337                 must "boolean(../node/termination-point[./destination/dest-tp])";
 338                     // Constraint: The destination termination point must be contained
 339                     // in the destination node
 340             }
 341         }
 342     }
 343
 344     notification n1 {
 345         description "This example defines a notification 1.";
 346         leaf event-class {
 347             type string;
 348         }
 349         anyxml reporting-entity;
 350         container severity {
 351             list links {
 352                 container endpoints {
 353                     leaf start {
 354                         type x;
 355                     }
 356                     leaf end {
 357                         type y;
 358                     }
 359                 }
 360                 leaf id {
 361                     type string;
 362                 }
 363             }
 364         }
 365     }
 366
 367     notification n2 {
 368         description "This example defines a notification 2.";
 369         leaf event-class {
 370             type string;
 371         }
 372         anyxml reporting-entity;
 373         leaf severity {
 374             type string;
 375         }
 376     }
 377
 378     augment "/network-topology" {
 379         anyxml any-a;
 380         anyxml any-b;
 381     }
 382
 383     augment "/network-topology/topology" {
 384         description "description of augment 2";
 385         reference "reference of augment 2";
 386         list list-a {}
 387         list list-b {
 388             leaf leaf-c {
 389                 type string;
 390             }
 391         }
 392     }
 393
 394     augment "/network-topology/topology/topology-types" {
 395         container container-c {
 396             leaf id {
 397                 type binary;
 398             }
 399         }
 400     }
 401
 402     rpc rock-the-house {
 403         description "This statement is used to define a NETCONF RPC operation.";
 404         reference "http://tools.ietf.org/html/rfc6020#section-7.13";
 405         input {
 406             leaf zip-code {
 407                 type string;
 408             }
 409         }
 410         output {
 411             leaf number {
 412                 type int32;
 413             }
 414         }
 415     }
 416
 417     extension c-define {
 418         description
 419             "Takes as argument a name string.
 420             Makes the code generator use the given name in the
 421             #define.";
 422         argument "name";
 423     }
 424
 425     feature local-storage {
 426         description
 427             "This feature means the device supports local
 428             storage (memory, flash or disk) that can be used to
 429             store syslog messages.";
 430     }
 431
 432 }