model/rfc8526/src/main/yang/ietf-netconf-nmda@2019-01-07.yang

   1 module ietf-netconf-nmda {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-nmda";
   4   prefix ncds;
   5
   6   import ietf-yang-types {
   7     prefix yang;
   8     reference
   9       "RFC 6991: Common YANG Data Types";
  10   }
  11   import ietf-inet-types {
  12     prefix inet;
  13     reference
  14       "RFC 6991: Common YANG Data Types";
  15   }
  16   import ietf-datastores {
  17     prefix ds;
  18     reference
  19       "RFC 8342: Network Management Datastore Architecture
  20                  (NMDA)";
  21   }
  22   import ietf-origin {
  23     prefix or;
  24     reference
  25       "RFC 8342: Network Management Datastore Architecture
  26                  (NMDA)";
  27   }
  28   import ietf-netconf {
  29     prefix nc;
  30     reference
  31       "RFC 6241: Network Configuration Protocol (NETCONF)";
  32   }
  33   import ietf-netconf-with-defaults {
  34     prefix ncwd;
  35     reference
  36       "RFC 6243: With-defaults Capability for NETCONF";
  37   }
  38
  39   organization
  40     "IETF NETCONF Working Group";
  41
  42   contact
  43     "WG Web:   <https://datatracker.ietf.org/wg/netconf/>
  44
  45      WG List:  <mailto:netconf@ietf.org>
  46
  47      Author:   Martin Bjorklund
  48                <mailto:mbj@tail-f.com>
  49
  50      Author:   Juergen Schoenwaelder
  51                <mailto:j.schoenwaelder@jacobs-university.de>
  52
  53      Author:   Phil Shafer
  54                <mailto:phil@juniper.net>
  55
  56      Author:   Kent Watsen
  57                <mailto:kent+ietf@watsen.net>
  58
  59      Author:   Robert Wilton
  60                <mailto:rwilton@cisco.com>";
  61   description
  62     "This YANG module defines a set of NETCONF operations to support
  63      the Network Management Datastore Architecture (NMDA).
  64
  65      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
  66      NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
  67      'MAY', and 'OPTIONAL' in this document are to be interpreted as
  68      described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
  69      they appear in all capitals, as shown here.
  70
  71      Copyright (c) 2019 IETF Trust and the persons identified as
  72      authors of the code.  All rights reserved.
  73
  74      Redistribution and use in source and binary forms, with or
  75      without modification, is permitted pursuant to, and subject to
  76      the license terms contained in, the Simplified BSD License set
  77      forth in Section 4.c of the IETF Trust's Legal Provisions
  78      Relating to IETF Documents
  79      (https://trustee.ietf.org/license-info).
  80
  81      This version of this YANG module is part of RFC 8526; see
  82      the RFC itself for full legal notices.";
  83
  84   revision 2019-01-07 {
  85     description
  86       "Initial revision.";
  87     reference
  88       "RFC 8526: NETCONF Extensions to Support the Network Management
  89                  Datastore Architecture";
  90   }
  91
  92   feature origin {
  93     description
  94       "Indicates that the server supports the 'origin' annotation.";
  95     reference
  96       "RFC 8342: Network Management Datastore Architecture (NMDA)";
  97   }
  98
  99   feature with-defaults {
 100     description
 101       "NETCONF :with-defaults capability.  If the server advertises
 102        the :with-defaults capability for a session, then this
 103        feature must also be enabled for that session.  Otherwise,
 104        this feature must not be enabled.";
 105     reference
 106       "RFC 6243: With-defaults Capability for NETCONF, Section 4; and
 107        RFC 8526: NETCONF Extensions to Support the Network Management
 108                  Datastore Architecture, Section 3.1.1.2";
 109   }
 110
 111   rpc get-data {
 112     description
 113       "Retrieve data from an NMDA datastore.  The content returned
 114        by get-data must satisfy all filters, i.e., the filter
 115        criteria are logically ANDed.
 116
 117        Any ancestor nodes (including list keys) of nodes selected by
 118        the filters are included in the response.
 119
 120        The 'with-origin' parameter is only valid for an operational
 121        datastore.  If 'with-origin' is used with an invalid
 122        datastore, then the server MUST return an <rpc-error> element
 123        with an <error-tag> value of 'invalid-value'.
 124
 125        The 'with-defaults' parameter only applies to the operational
 126        datastore if the NETCONF :with-defaults and
 127        :with-operational-defaults capabilities are both advertised.
 128        If the 'with-defaults' parameter is present in a request for
 129        which it is not supported, then the server MUST return an
 130        <rpc-error> element with an <error-tag> value of
 131        'invalid-value'.";
 132     input {
 133       leaf datastore {
 134         type ds:datastore-ref;
 135         mandatory true;
 136
 137         description
 138           "Datastore from which to retrieve data.
 139
 140            If the datastore is not supported by the server, then the
 141            server MUST return an <rpc-error> element with an
 142            <error-tag> value of 'invalid-value'.";
 143       }
 144       choice filter-spec {
 145         description
 146           "The content filter specification for this request.";
 147         anydata subtree-filter {
 148           description
 149             "This parameter identifies the portions of the
 150              target datastore to retrieve.";
 151           reference
 152             "RFC 6241: Network Configuration Protocol (NETCONF),
 153                        Section 6";
 154         }
 155         leaf xpath-filter {
 156           if-feature "nc:xpath";
 157           type yang:xpath1.0;
 158           description
 159             "This parameter contains an XPath expression identifying
 160              the portions of the target datastore to retrieve.
 161
 162              If the expression returns a node-set, all nodes in the
 163              node-set are selected by the filter.  Otherwise, if the
 164              expression does not return a node-set, then the
 165              <get-data> operation fails.
 166
 167              The expression is evaluated in the following XPath
 168              context:
 169
 170                o  The set of namespace declarations are those in
 171                   scope on the 'xpath-filter' leaf element.
 172
 173                o  The set of variable bindings is empty.
 174
 175                o  The function library is the core function library,
 176                   and the XPath functions are defined in Section 10
 177                   of RFC 7950.
 178
 179                o  The context node is the root node of the target
 180                   datastore.";
 181         }
 182       }
 183       leaf config-filter {
 184         type boolean;
 185         description
 186           "Filter for nodes with the given value for their 'config'
 187            property.  When this leaf is set to 'true', only 'config
 188            true' nodes are selected, and when set to 'false', only
 189            'config false' nodes are selected.  If this leaf is not
 190            present, no nodes are filtered.";
 191       }
 192       choice origin-filters {
 193         when 'derived-from-or-self(datastore, "ds:operational")';
 194         if-feature "origin";
 195         description
 196           "Filters configuration nodes based on the 'origin'
 197            annotation.  Configuration nodes that do not have an
 198            'origin' annotation are treated as if they have the
 199            'origin' annotation 'or:unknown'.
 200
 201            System state nodes are not affected by origin-filters and
 202            thus not filtered.  Note that system state nodes can be
 203            filtered with the 'config-filter' leaf.";
 204
 205         leaf-list origin-filter {
 206           type or:origin-ref;
 207           description
 208             "Filter based on the 'origin' annotation.  A
 209              configuration node matches the filter if its 'origin'
 210              annotation is derived from or equal to any of the given
 211              filter values.";
 212         }
 213         leaf-list negated-origin-filter {
 214           type or:origin-ref;
 215           description
 216             "Filter based on the 'origin' annotation.  A
 217              configuration node matches the filter if its 'origin'
 218              annotation is neither derived from nor equal to any of
 219              the given filter values.";
 220         }
 221       }
 222       leaf max-depth {
 223         type union {
 224           type uint16 {
 225             range "1..65535";
 226           }
 227           type enumeration {
 228             enum unbounded {
 229               description
 230                 "All descendant nodes are included.";
 231             }
 232           }
 233         }
 234         default "unbounded";
 235         description
 236           "For each node selected by the filters, this parameter
 237            selects how many conceptual subtree levels should be
 238            returned in the reply.  If the depth is 1, the reply
 239            includes just the selected nodes but no children.  If the
 240            depth is 'unbounded', all descendant nodes are included.";
 241       }
 242       leaf with-origin {
 243         when 'derived-from-or-self(../datastore, "ds:operational")';
 244         if-feature "origin";
 245         type empty;
 246         description
 247           "If this parameter is present, the server will return
 248            the 'origin' annotation for the nodes that have one.";
 249       }
 250       uses ncwd:with-defaults-parameters {
 251         if-feature "with-defaults";
 252       }
 253     }
 254     output {
 255       anydata data {
 256         description
 257           "Copy of the source datastore subset that matched
 258            the filter criteria (if any).  An empty data
 259            container indicates that the request did not
 260            produce any results.";
 261       }
 262     }
 263   }
 264
 265   rpc edit-data {
 266     description
 267       "Edit data in an NMDA datastore.
 268
 269        If an error condition occurs such that an error severity
 270        <rpc-error> element is generated, the server will stop
 271        processing the <edit-data> operation and restore the
 272        specified configuration to its complete state at
 273        the start of this <edit-data> operation.";
 274     input {
 275       leaf datastore {
 276         type ds:datastore-ref;
 277         mandatory true;
 278
 279         description
 280           "Datastore that is the target of the <edit-data> operation.
 281
 282            If the target datastore is not writable, or is not
 283            supported by the server, then the server MUST return an
 284            <rpc-error> element with an <error-tag> value of
 285            'invalid-value'.";
 286       }
 287       leaf default-operation {
 288         type enumeration {
 289           enum merge {
 290             description
 291               "The default operation is merge.";
 292           }
 293           enum replace {
 294             description
 295               "The default operation is replace.";
 296           }
 297           enum none {
 298             description
 299               "There is no default operation.";
 300           }
 301         }
 302         default "merge";
 303         description
 304           "The default operation to use.";
 305       }
 306       choice edit-content {
 307         mandatory true;
 308         description
 309           "The content for the edit operation.";
 310         anydata config {
 311           description
 312             "Inline config content.";
 313         }
 314         leaf url {
 315           if-feature "nc:url";
 316           type inet:uri;
 317           description
 318             "URL-based config content.";
 319         }
 320       }
 321     }
 322   }
 323
 324   /*
 325    * Augment the <lock> and <unlock> operations with a
 326    * "datastore" parameter.
 327    */
 328
 329   augment "/nc:lock/nc:input/nc:target/nc:config-target" {
 330     description
 331       "Add NMDA datastore as target.";
 332     leaf datastore {
 333       type ds:datastore-ref;
 334       description
 335         "Datastore to lock.
 336
 337          The <lock> operation is only supported on writable
 338          datastores.
 339
 340          If the <lock> operation is not supported by the server on
 341          the specified target datastore, then the server MUST return
 342          an <rpc-error> element with an <error-tag> value of
 343          'invalid-value'.";
 344     }
 345   }
 346
 347   augment "/nc:unlock/nc:input/nc:target/nc:config-target" {
 348     description
 349       "Add NMDA datastore as target.";
 350     leaf datastore {
 351       type ds:datastore-ref;
 352       description
 353         "Datastore to unlock.
 354
 355          The <unlock> operation is only supported on writable
 356          datastores.
 357
 358          If the <unlock> operation is not supported by the server on
 359          the specified target datastore, then the server MUST return
 360          an <rpc-error> element with an <error-tag> value of
 361          'invalid-value'.";
 362     }
 363   }
 364
 365   /*
 366    * Augment the <validate> operation with a
 367    * "datastore" parameter.
 368    */
 369
 370   augment "/nc:validate/nc:input/nc:source/nc:config-source" {
 371     description
 372       "Add NMDA datastore as source.";
 373     leaf datastore {
 374       type ds:datastore-ref;
 375       description
 376         "Datastore to validate.
 377
 378          The <validate> operation is supported only on configuration
 379          datastores.
 380
 381          If the <validate> operation is not supported by the server
 382          on the specified target datastore, then the server MUST
 383          return an <rpc-error> element with an <error-tag> value of
 384          'invalid-value'.";
 385     }
 386   }
 387 }