opendaylight/md-sal/sal-rest-connector/src/test/resources/modules/ietf-restconf@2013-10-19.yang

   1 module ietf-restconf {
   2      namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
   3      prefix "restconf";
   4
   5      import ietf-yang-types { prefix yang; }
   6      import ietf-inet-types { prefix inet; }
   7
   8      organization
   9        "IETF NETCONF (Network Configuration) Working Group";
  10
  11      contact
  12        "Editor:   Andy Bierman
  13                   <mailto:andy@yumaworks.com>
  14
  15         Editor:   Martin Bjorklund
  16                   <mailto:mbj@tail-f.com>
  17
  18         Editor:   Kent Watsen
  19                   <mailto:kwatsen@juniper.net>
  20
  21         Editor:   Rex Fernando
  22                   <mailto:rex@cisco.com>";
  23
  24      description
  25        "This module contains conceptual YANG specifications
  26         for the YANG Patch and error content that is used in
  27         RESTCONF protocol messages. A conceptual container
  28         representing the RESTCONF API nodes (media type
  29         application/yang.api).
  30
  31         Note that the YANG definitions within this module do not
  32         represent configuration data of any kind.
  33         The YANG grouping statements provide a normative syntax
  34         for XML and JSON message encoding purposes.
  35         Copyright (c) 2013 IETF Trust and the persons identified as
  36         authors of the code.  All rights reserved.
  37
  38         Redistribution and use in source and binary forms, with or
  39         without modification, is permitted pursuant to, and subject
  40         to the license terms contained in, the Simplified BSD License
  41         set forth in Section 4.c of the IETF Trust's Legal Provisions
  42         Relating to IETF Documents
  43         (http://trustee.ietf.org/license-info).
  44
  45         This version of this YANG module is part of RFC XXXX; see
  46         the RFC itself for full legal notices.";
  47
  48      // RFC Ed.: replace XXXX with actual RFC number and remove this
  49      // note.
  50
  51      // RFC Ed.: remove this note
  52      // Note: extracted from draft-bierman-netconf-restconf-02.txt
  53
  54      // RFC Ed.: update the date below with the date of RFC publication
  55      // and remove this note.
  56      revision 2013-10-19 {
  57        description
  58          "Initial revision.";
  59        reference
  60          "RFC XXXX: RESTCONF Protocol.";
  61      }
  62
  63      typedef data-resource-identifier {
  64        type string {
  65          length "1 .. max";
  66        }
  67        description
  68          "Contains a Data Resource Identifier formatted string
  69           to identify a specific data node. The data node that
  70           uses this data type SHOULD define the document root
  71           for data resource identifiers.  The default document
  72           root is the target datastore conceptual root node.
  73           Data resource identifiers are defined relative to
  74           this document root.";
  75        reference
  76          "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]";
  77      }
  78
  79      // this typedef is TBD; not currently used
  80      typedef datastore-identifier {
  81        type union {
  82          type enumeration {
  83            enum candidate {
  84              description
  85                "Identifies the NETCONF shared candidate datastore.";
  86              reference
  87                "RFC 6241, section 8.3";
  88            }
  89            enum running {
  90              description
  91                "Identifies the NETCONF running datastore.";
  92              reference
  93                "RFC 6241, section 5.1";
  94            }
  95            enum startup {
  96              description
  97                "Identifies the NETCONF startup datastore.";
  98              reference
  99                "RFC 6241, section 8.7";
 100            }
 101          }
 102          type string;
 103        }
 104        description
 105          "Contains a string to identify a specific datastore.
 106           The enumerated datastore identifier values are
 107           reserved for standard datastore names.";
 108      }
 109
 110      typedef revision-identifier {
 111        type string {
 112          pattern '\d{4}-\d{2}-\d{2}';
 113        }
 114        description
 115          "Represents a specific date in YYYY-MM-DD format.
 116           TBD: make pattern more precise to exclude leading zeros.";
 117      }
 118
 119      grouping yang-patch {
 120        description
 121          "A grouping that contains a YANG container
 122           representing the syntax and semantics of a
 123           YANG Patch edit request message.";
 124
 125        container yang-patch {
 126          description
 127            "Represents a conceptual sequence of datastore edits,
 128             called a patch. Each patch is given a client-assigned
 129             patch identifier. Each edit MUST be applied
 130             in ascending order, and all edits MUST be applied.
 131             If any errors occur, then the target datastore MUST NOT
 132             be changed by the patch operation.
 133
 134             A patch MUST be validated by the server to be a
 135             well-formed message before any of the patch edits
 136             are validated or attempted.
 137
 138             YANG datastore validation (defined in RFC 6020, section
 139             8.3.3) is performed after all edits have been
 140             individually validated.
 141
 142             It is possible for a datastore constraint violation to occur
 143             due to any node in the datastore, including nodes not
 144             included in the edit list. Any validation errors MUST
 145             be reported in the reply message.";
 146
 147          reference
 148            "RFC 6020, section 8.3.";
 149
 150          leaf patch-id {
 151            type string;
 152            description
 153              "An arbitrary string provided by the client to identify
 154               the entire patch.  This value SHOULD be present in any
 155               audit logging records generated by the server for the
 156               patch. Error messages returned by the server pertaining
 157               to this patch will be identified by this patch-id value.";
 158          }
 159
 160          leaf comment {
 161            type string {
 162              length "0 .. 1024";
 163            }
 164            description
 165              "An arbitrary string provided by the client to describe
 166               the entire patch.  This value SHOULD be present in any
 167               audit logging records generated by the server for the
 168               patch.";
 169          }
 170
 171          list edit {
 172            key edit-id;
 173            ordered-by user;
 174
 175            description
 176              "Represents one edit within the YANG Patch
 177               request message.";
 178            leaf edit-id {
 179              type string;
 180              description
 181                "Arbitrary string index for the edit.
 182                 Error messages returned by the server pertaining
 183                 to a specific edit will be identified by this
 184                 value.";
 185            }
 186
 187            leaf operation {
 188              type enumeration {
 189                enum create {
 190                  description
 191                    "The target data node is created using the
 192                     supplied value, only if it does not already
 193                     exist.";
 194                }
 195                enum delete {
 196                  description
 197                    "Delete the target node, only if the data resource
 198                     currently exists, otherwise return an error.";
 199                }
 200                enum insert {
 201                  description
 202                    "Insert the supplied value into a user-ordered
 203                     list or leaf-list entry. The target node must
 204                     represent a new data resource.";
 205                }
 206                enum merge {
 207                  description
 208                    "The supplied value is merged with the target data
 209                     node.";
 210                }
 211                enum move {
 212                  description
 213                    "Move the target node. Reorder a user-ordered
 214                     list or leaf-list. The target node must represent
 215                     an existing data resource.";
 216                }
 217                enum replace {
 218                  description
 219                    "The supplied value is used to replace the target
 220                     data node.";
 221                }
 222                enum remove {
 223                  description
 224                    "Delete the target node if it currently exists.";
 225                }
 226              }
 227              mandatory true;
 228              description
 229                "The datastore operation requested for the associated
 230                 edit entry";
 231            }
 232
 233            leaf target {
 234              type data-resource-identifier;
 235              mandatory true;
 236              description
 237                "Identifies the target data resource for the edit
 238                 operation.";
 239            }
 240
 241            leaf point {
 242              when "(../operation = 'insert' or " +
 243                "../operation = 'move') and " +
 244                "(../where = 'before' or ../where = 'after')" {
 245                description
 246                  "Point leaf only applies for insert or move
 247                   operations, before or after an existing entry.";
 248              }
 249              type data-resource-identifier;
 250              description
 251                "The absolute URL path for the data node that is being
 252                 used as the insertion point or move point for the
 253                 target of this edit entry.";
 254            }
 255
 256            leaf where {
 257              when "../operation = 'insert' or ../operation = 'move'" {
 258                description
 259                  "Where leaf only applies for insert or move
 260                   operations.";
 261              }
 262              type enumeration {
 263                enum before {
 264                  description
 265                    "Insert or move a data node before the data resource
 266                     identified by the 'point' parameter.";
 267                }
 268                enum after {
 269                  description
 270                    "Insert or move a data node after the data resource
 271                     identified by the 'point' parameter.";
 272                }
 273                enum first {
 274                  description
 275                    "Insert or move a data node so it becomes ordered
 276                     as the first entry.";
 277                }
 278                enum last {
 279                  description
 280                    "Insert or move a data node so it becomes ordered
 281                     as the last entry.";
 282                }
 283
 284              }
 285              default last;
 286              description
 287                "Identifies where a data resource will be inserted or
 288                 moved. YANG only allows these operations for
 289                 list and leaf-list data nodes that are ordered-by
 290                 user.";
 291            }
 292
 293            anyxml value {
 294              when "(../operation = 'create' or " +
 295                "../operation = 'merge' " +
 296                "or ../operation = 'replace' or " +
 297                "../operation = 'insert')" {
 298                description
 299                  "Value node only used for create, merge,
 300                   replace, and insert operations";
 301              }
 302              description
 303                "Value used for this edit operation.";
 304            }
 305          }
 306        }
 307
 308      } // grouping yang-patch
 309
 310
 311      grouping yang-patch-status {
 312
 313        description
 314          "A grouping that contains a YANG container
 315           representing the syntax and semantics of
 316           YANG Patch status response message.";
 317
 318        container yang-patch-status {
 319          description
 320            "A container representing the response message
 321             sent by the server after a YANG Patch edit
 322             request message has been processed.";
 323
 324          leaf patch-id {
 325            type string;
 326            description
 327              "The patch-id value used in the request";
 328          }
 329
 330          choice global-status {
 331            description
 332              "Report global errors or complete success.
 333               If there is no case selected then errors
 334               are reported in the edit-status container.";
 335
 336            case global-errors {
 337              uses errors;
 338              description
 339                "This container will be present if global
 340                 errors unrelated to a specific edit occurred.";
 341            }
 342            leaf ok {
 343              type empty;
 344              description
 345                "This leaf will be present if the request succeeded
 346                 and there are no errors reported in the edit-status
 347                 container.";
 348            }
 349          }
 350
 351          container edit-status {
 352            description
 353              "This container will be present if there are
 354               edit-specific status responses to report.";
 355
 356            list edit {
 357              key edit-id;
 358
 359              description
 360                "Represents a list of status responses,
 361                 corresponding to edits in the YANG Patch
 362                 request message.  If an edit entry was
 363                 skipped or not reached by the server,
 364                 then this list will not contain a corresponding
 365                 entry for that edit.";
 366
 367              leaf edit-id {
 368                type string;
 369                 description
 370                   "Response status is for the edit list entry
 371                    with this edit-id value.";
 372              }
 373              choice edit-status-choice {
 374                description
 375                  "A choice between different types of status
 376                   responses for each edit entry.";
 377                leaf ok {
 378                  type empty;
 379                  description
 380                    "This edit entry was invoked without any
 381                     errors detected by the server associated
 382                     with this edit.";
 383                }
 384                leaf location {
 385                  type inet:uri;
 386                  description
 387                    "Contains the Location header value that would be
 388                     returned if this edit causes a new resource to be
 389                     created. If the edit identified by the same edit-id
 390                     value was successfully invoked and a new resource
 391                     was created, then this field will be returned
 392                     instead of 'ok'.";
 393                }
 394                case errors {
 395                  uses errors;
 396                  description
 397                    "The server detected errors associated with the
 398                      edit identified by the same edit-id value.";
 399                }
 400              }
 401            }
 402          }
 403        }
 404      }  // grouping yang-patch-status
 405
 406
 407      grouping errors {
 408
 409        description
 410          "A grouping that contains a YANG container
 411           representing the syntax and semantics of a
 412           YANG Patch errors report within a response message.";
 413
 414        container errors {
 415          config false;  // needed so list error does not need a key
 416          description
 417            "Represents an error report returned by the server if
 418             a request results in an error.";
 419
 420          list error {
 421            description
 422              "An entry containing information about one
 423               specific error that occurred while processing
 424               a RESTCONF request.";
 425            reference "RFC 6241, Section 4.3";
 426
 427            leaf error-type {
 428              type enumeration {
 429                enum transport {
 430                  description "The transport layer";
 431                }
 432                enum rpc {
 433                  description "The rpc or notification layer";
 434                }
 435                enum protocol {
 436                  description "The protocol operation layer";
 437                }
 438                enum application {
 439                  description "The server application layer";
 440                }
 441              }
 442              mandatory true;
 443              description
 444                "The protocol layer where the error occurred.";
 445            }
 446
 447            leaf error-tag {
 448              type string;
 449              mandatory true;
 450              description
 451                "The enumerated error tag.";
 452            }
 453
 454            leaf error-app-tag {
 455              type string;
 456              description
 457                "The application-specific error tag.";
 458            }
 459
 460            leaf error-path {
 461              type data-resource-identifier;
 462              description
 463                "The target data resource identifier associated
 464                 with the error, if any.";
 465            }
 466            leaf error-message {
 467              type string;
 468              description
 469                "A message describing the error.";
 470            }
 471
 472            container error-info {
 473               description
 474                 "A container allowing additional information
 475                  to be included in the error report.";
 476               // arbitrary anyxml content here
 477            }
 478          }
 479        }
 480      } // grouping errors
 481
 482
 483      grouping restconf {
 484
 485        description
 486          "A grouping that contains a YANG container
 487           representing the syntax and semantics of
 488           the RESTCONF API resource.";
 489
 490        container restconf {
 491          description
 492            "Conceptual container representing the
 493             application/yang.api resource type.";
 494
 495          container config {
 496            description
 497              "Container representing the application/yang.datastore
 498               resource type. Represents the conceptual root of the
 499               unified configuration datastore containing YANG data
 500               nodes. The child nodes of this container are
 501               configuration data resources (application/yang.data)
 502               defined as top-level YANG data nodes from the modules
 503               advertised by the server in /restconf/modules.";
 504          }
 505
 506          container operational {
 507            description
 508              "Container representing the application/yang.datastore
 509               resource type. Represents the conceptual root of the
 510               operational data supported by the server.  The child
 511               nodes of this container are operational data resources
 512               (application/yang.data) defined as top-level
 513               YANG data nodes from the modules advertised by
 514               the server in /restconf/modules.";
 515          }
 516
 517          container modules {
 518            description
 519              "Contains a list of module description entries.
 520               These modules are currently loaded into the server.";
 521
 522            list module {
 523              key "name revision";
 524              description
 525                "Each entry represents one module currently
 526                 supported by the server.";
 527
 528              leaf name {
 529                type yang:yang-identifier;
 530                description "The YANG module name.";
 531              }
 532              leaf revision {
 533                type union {
 534                  type revision-identifier;
 535                  type string { length 0; }
 536                }
 537                description
 538                  "The YANG module revision date. An empty string is
 539                   used if no revision statement is present in the
 540                   YANG module.";
 541              }
 542              leaf namespace {
 543                type inet:uri;
 544                mandatory true;
 545                description
 546                  "The XML namespace identifier for this module.";
 547              }
 548              leaf-list feature {
 549                type yang:yang-identifier;
 550                description
 551                  "List of YANG feature names from this module that are
 552                   supported by the server.";
 553              }
 554              leaf-list deviation {
 555                type yang:yang-identifier;
 556                description
 557                  "List of YANG deviation module names used by this
 558                   server to modify the conformance of the module
 559                   associated with this entry.";
 560              }
 561            }
 562          }
 563
 564          container operations {
 565            description
 566              "Container for all operation resources
 567               (application/yang.operation),
 568
 569               Each resource is represented as an empty leaf with the
 570               name of the RPC operation from the YANG rpc statement.
 571
 572               E.g.;
 573
 574                  POST /restconf/operations/show-log-errors
 575
 576                  leaf show-log-errors {
 577                    type empty;
 578                  }
 579              ";
 580          }
 581
 582          container streams {
 583            description
 584              "Container representing the notification event streams
 585               supported by the server.";
 586             reference
 587               "RFC 5277, Section 3.4, <streams> element.";
 588
 589            list stream {
 590              key name;
 591              description
 592                "Each entry describes an event stream supported by
 593                 the server.";
 594
 595              leaf name {
 596                type string;
 597                description "The stream name";
 598                reference "RFC 5277, Section 3.4, <name> element.";
 599              }
 600
 601              leaf description {
 602                type string;
 603                description "Description of stream content";
 604                reference
 605                  "RFC 5277, Section 3.4, <description> element.";
 606              }
 607
 608              leaf replay-support {
 609                type boolean;
 610                description
 611                  "Indicates if replay buffer supported for this stream";
 612                reference
 613                  "RFC 5277, Section 3.4, <replaySupport> element.";
 614              }
 615
 616              leaf replay-log-creation-time {
 617                type yang:date-and-time;
 618                description
 619                  "Indicates the time the replay log for this stream
 620                   was created.";
 621                reference
 622                  "RFC 5277, Section 3.4, <replayLogCreationTime>
 623                   element.";
 624              }
 625
 626              leaf events {
 627                type empty;
 628                description
 629                  "Represents the entry point for establishing
 630                   notification delivery via server sent events.";
 631              }
 632            }
 633          }
 634
 635          leaf version {
 636            type enumeration {
 637              enum "1.0" {
 638                description
 639                  "Version 1.0 of the RESTCONF protocol.";
 640              }
 641            }
 642            config false;
 643            description
 644              "Contains the RESTCONF protocol version.";
 645          }
 646        }
 647      }  // grouping restconf
 648
 649
 650      grouping notification {
 651        description
 652          "Contains the notification message wrapper definition.";
 653
 654        container notification {
 655          description
 656            "RESTCONF notification message wrapper.";
 657          leaf event-time {
 658            type yang:date-and-time;
 659            mandatory true;
 660            description
 661              "The time the event was generated by the
 662               event source.";
 663            reference
 664              "RFC 5277, section 4, <eventTime> element.";
 665          }
 666
 667          /* The YANG-specific notification container is encoded
 668           * after the 'event-time' element.  The format
 669           * corresponds to the notificationContent element
 670           * in RFC 5277, section 4. For example:
 671           *
 672           *  module example-one {
 673           *     ...
 674           *     notification event1 { ... }
 675           *
 676           *  }
 677           *
 678           *  Encoded as element 'event1' in the namespace
 679           *  for module 'example-one'.
 680           */
 681        }
 682      }  // grouping notification
 683
 684    }