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