restconf/restconf-models/ietf-yang-patch/src/main/yang/ietf-yang-patch@2017-02-22.yang

   1 module ietf-yang-patch {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch";
   4   prefix "ypatch";
   5
   6   import ietf-restconf { prefix rc; }
   7
   8   organization
   9     "IETF NETCONF (Network Configuration) Working Group";
  10
  11   contact
  12     "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
  13      WG List:  <mailto:netconf@ietf.org>
  14
  15      Author:   Andy Bierman
  16                <mailto:andy@yumaworks.com>
  17
  18      Author:   Martin Bjorklund
  19                <mailto:mbj@tail-f.com>
  20
  21      Author:   Kent Watsen
  22                <mailto:kwatsen@juniper.net>";
  23
  24   description
  25     "This module contains conceptual YANG specifications
  26      for the YANG Patch and YANG Patch Status data structures.
  27
  28      Note that the YANG definitions within this module do not
  29      represent configuration data of any kind.
  30      The YANG grouping statements provide a normative syntax
  31      for XML and JSON message-encoding purposes.
  32
  33      Copyright (c) 2017 IETF Trust and the persons identified as
  34      authors of the code.  All rights reserved.
  35
  36      Redistribution and use in source and binary forms, with or
  37      without modification, is permitted pursuant to, and subject
  38      to the license terms contained in, the Simplified BSD License
  39      set forth in Section 4.c of the IETF Trust's Legal Provisions
  40      Relating to IETF Documents
  41      (http://trustee.ietf.org/license-info).
  42
  43      This version of this YANG module is part of RFC 8072; see
  44      the RFC itself for full legal notices.";
  45
  46   revision 2017-02-22 {
  47     description
  48       "Initial revision.";
  49     reference
  50       "RFC 8072: YANG Patch Media Type.";
  51   }
  52
  53   typedef target-resource-offset {
  54     type string;
  55     description
  56       "Contains a data resource identifier string representing
  57        a sub-resource within the target resource.
  58        The document root for this expression is the
  59        target resource that is specified in the
  60        protocol operation (e.g., the URI for the PATCH request).
  61
  62        This string is encoded according to the same rules as those
  63        for a data resource identifier in a RESTCONF request URI.";
  64     reference
  65        "RFC 8040, Section 3.5.3.";
  66   }
  67
  68   rc:yang-data "yang-patch" {
  69     uses yang-patch;
  70   }
  71
  72   rc:yang-data "yang-patch-status" {
  73     uses yang-patch-status;
  74   }
  75
  76   grouping yang-patch {
  77
  78     description
  79       "A grouping that contains a YANG container representing the
  80        syntax and semantics of a YANG Patch edit request message.";
  81
  82     container yang-patch {
  83       description
  84         "Represents a conceptual sequence of datastore edits,
  85          called a patch.  Each patch is given a client-assigned
  86          patch identifier.  Each edit MUST be applied
  87          in ascending order, and all edits MUST be applied.
  88          If any errors occur, then the target datastore MUST NOT
  89          be changed by the YANG Patch operation.
  90
  91          It is possible for a datastore constraint violation to occur
  92          due to any node in the datastore, including nodes not
  93          included in the 'edit' list.  Any validation errors MUST
  94          be reported in the reply message.";
  95
  96       reference
  97         "RFC 7950, Section 8.3.";
  98
  99       leaf patch-id {
 100         type string;
 101         mandatory true;
 102         description
 103           "An arbitrary string provided by the client to identify
 104            the entire patch.  Error messages returned by the server
 105            that pertain to this patch will be identified by this
 106            'patch-id' value.  A client SHOULD attempt to generate
 107            unique 'patch-id' values to distinguish between
 108            transactions from multiple clients in any audit logs
 109            maintained by the server.";
 110       }
 111
 112       leaf comment {
 113         type string;
 114         description
 115           "An arbitrary string provided by the client to describe
 116            the entire patch.  This value SHOULD be present in any
 117            audit logging records generated by the server for the
 118            patch.";
 119       }
 120
 121       list edit {
 122         key edit-id;
 123         ordered-by user;
 124
 125         description
 126           "Represents one edit within the YANG Patch request message.
 127            The 'edit' list is applied in the following manner:
 128
 129              - The first edit is conceptually applied to a copy
 130                of the existing target datastore, e.g., the
 131                running configuration datastore.
 132              - Each ascending edit is conceptually applied to
 133                the result of the previous edit(s).
 134              - After all edits have been successfully processed,
 135                the result is validated according to YANG constraints.
 136              - If successful, the server will attempt to apply
 137                the result to the target datastore.";
 138
 139         leaf edit-id {
 140           type string;
 141           description
 142             "Arbitrary string index for the edit.
 143              Error messages returned by the server that pertain
 144              to a specific edit will be identified by this value.";
 145         }
 146
 147         leaf operation {
 148           type enumeration {
 149             enum create {
 150               description
 151                 "The target data node is created using the supplied
 152                  value, only if it does not already exist.  The
 153                  'target' leaf identifies the data node to be
 154                  created, not the parent data node.";
 155             }
 156             enum delete {
 157               description
 158                 "Delete the target node, only if the data resource
 159                  currently exists; otherwise, return an error.";
 160             }
 161
 162             enum insert {
 163               description
 164                 "Insert the supplied value into a user-ordered
 165                  list or leaf-list entry.  The target node must
 166                  represent a new data resource.  If the 'where'
 167                  parameter is set to 'before' or 'after', then
 168                  the 'point' parameter identifies the insertion
 169                  point for the target node.";
 170             }
 171             enum merge {
 172               description
 173                 "The supplied value is merged with the target data
 174                  node.";
 175             }
 176             enum move {
 177               description
 178                 "Move the target node.  Reorder a user-ordered
 179                  list or leaf-list.  The target node must represent
 180                  an existing data resource.  If the 'where' parameter
 181                  is set to 'before' or 'after', then the 'point'
 182                  parameter identifies the insertion point to move
 183                  the target node.";
 184             }
 185             enum replace {
 186               description
 187                 "The supplied value is used to replace the target
 188                  data node.";
 189             }
 190             enum remove {
 191               description
 192                 "Delete the target node if it currently exists.";
 193             }
 194           }
 195           mandatory true;
 196           description
 197             "The datastore operation requested for the associated
 198              'edit' entry.";
 199         }
 200
 201         leaf target {
 202           type target-resource-offset;
 203           mandatory true;
 204           description
 205             "Identifies the target data node for the edit
 206              operation.  If the target has the value '/', then
 207              the target data node is the target resource.
 208              The target node MUST identify a data resource,
 209              not the datastore resource.";
 210         }
 211
 212         leaf point {
 213           when "(../operation = 'insert' or ../operation = 'move')"
 214              + "and (../where = 'before' or ../where = 'after')" {
 215             description
 216               "This leaf only applies for 'insert' or 'move'
 217                operations, before or after an existing entry.";
 218           }
 219           type target-resource-offset;
 220           description
 221             "The absolute URL path for the data node that is being
 222              used as the insertion point or move point for the
 223              target of this 'edit' entry.";
 224         }
 225
 226         leaf where {
 227           when "../operation = 'insert' or ../operation = 'move'" {
 228             description
 229               "This leaf only applies for 'insert' or 'move'
 230                operations.";
 231           }
 232           type enumeration {
 233             enum before {
 234               description
 235                 "Insert or move a data node before the data resource
 236                  identified by the 'point' parameter.";
 237             }
 238             enum after {
 239               description
 240                 "Insert or move a data node after the data resource
 241                  identified by the 'point' parameter.";
 242             }
 243
 244             enum first {
 245               description
 246                 "Insert or move a data node so it becomes ordered
 247                  as the first entry.";
 248             }
 249             enum last {
 250               description
 251                 "Insert or move a data node so it becomes ordered
 252                  as the last entry.";
 253             }
 254           }
 255           default last;
 256           description
 257             "Identifies where a data resource will be inserted
 258              or moved.  YANG only allows these operations for
 259              list and leaf-list data nodes that are
 260              'ordered-by user'.";
 261         }
 262
 263         anydata value {
 264           when "../operation = 'create' "
 265              + "or ../operation = 'merge' "
 266              + "or ../operation = 'replace' "
 267              + "or ../operation = 'insert'" {
 268             description
 269               "The anydata 'value' is only used for 'create',
 270                'merge', 'replace', and 'insert' operations.";
 271           }
 272           description
 273             "Value used for this edit operation.  The anydata 'value'
 274              contains the target resource associated with the
 275              'target' leaf.
 276
 277              For example, suppose the target node is a YANG container
 278              named foo:
 279
 280                  container foo {
 281                    leaf a { type string; }
 282                    leaf b { type int32; }
 283                  }
 284
 285              The 'value' node contains one instance of foo:
 286
 287                  <value>
 288                     <foo xmlns='example-foo-namespace'>
 289                        <a>some value</a>
 290                        <b>42</b>
 291                     </foo>
 292                  </value>
 293               ";
 294         }
 295       }
 296     }
 297
 298   } // grouping yang-patch
 299
 300   grouping yang-patch-status {
 301
 302     description
 303       "A grouping that contains a YANG container representing the
 304        syntax and semantics of a YANG Patch Status response
 305        message.";
 306
 307     container yang-patch-status {
 308       description
 309         "A container representing the response message sent by the
 310          server after a YANG Patch edit request message has been
 311          processed.";
 312
 313       leaf patch-id {
 314         type string;
 315         mandatory true;
 316         description
 317           "The 'patch-id' value used in the request.";
 318       }
 319
 320       choice global-status {
 321         description
 322           "Report global errors or complete success.
 323            If there is no case selected, then errors
 324            are reported in the 'edit-status' container.";
 325
 326         case global-errors {
 327           uses rc:errors;
 328           description
 329             "This container will be present if global errors that
 330              are unrelated to a specific edit occurred.";
 331         }
 332         leaf ok {
 333           type empty;
 334           description
 335             "This leaf will be present if the request succeeded
 336              and there are no errors reported in the 'edit-status'
 337              container.";
 338         }
 339       }
 340
 341       container edit-status {
 342         description
 343           "This container will be present if there are
 344            edit-specific status responses to report.
 345            If all edits succeeded and the 'global-status'
 346            returned is 'ok', then a server MAY omit this
 347            container.";
 348
 349         list edit {
 350           key edit-id;
 351
 352           description
 353             "Represents a list of status responses,
 354              corresponding to edits in the YANG Patch
 355              request message.  If an 'edit' entry was
 356              skipped or not reached by the server,
 357              then this list will not contain a corresponding
 358              entry for that edit.";
 359
 360           leaf edit-id {
 361             type string;
 362              description
 363                "Response status is for the 'edit' list entry
 364                 with this 'edit-id' value.";
 365           }
 366
 367           choice edit-status-choice {
 368             description
 369               "A choice between different types of status
 370                responses for each 'edit' entry.";
 371             leaf ok {
 372               type empty;
 373               description
 374                 "This 'edit' entry was invoked without any
 375                  errors detected by the server associated
 376                  with this edit.";
 377             }
 378             case errors {
 379               uses rc:errors;
 380               description
 381                 "The server detected errors associated with the
 382                  edit identified by the same 'edit-id' value.";
 383             }
 384           }
 385         }
 386       }
 387     }
 388   }  // grouping yang-patch-status
 389
 390 }