ntsimulator/deploy/o-ran-ru-fh/yang/ietf-subscribed-notifications@2019-09-09.yang

   1 module ietf-subscribed-notifications {
   2   yang-version 1.1;
   3   namespace "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications";
   4   prefix sn;
   5
   6   import ietf-inet-types {
   7     prefix inet;
   8     reference
   9       "RFC 6991: Common YANG Data Types";
  10   }
  11   import ietf-interfaces {
  12     prefix if;
  13     reference
  14       "RFC 8343: A YANG Data Model for Interface Management";
  15   }
  16   import ietf-netconf-acm {
  17     prefix nacm;
  18     reference
  19       "RFC 8341: Network Configuration Access Control Model";
  20   }
  21   import ietf-network-instance {
  22     prefix ni;
  23     reference
  24       "RFC 8529: YANG Data Model for Network Instances";
  25   }
  26   import ietf-restconf {
  27     prefix rc;
  28     reference
  29       "RFC 8040: RESTCONF Protocol";
  30   }
  31   import ietf-yang-types {
  32     prefix yang;
  33     reference
  34       "RFC 6991: Common YANG Data Types";
  35   }
  36
  37   organization
  38     "IETF NETCONF (Network Configuration) Working Group";
  39   contact
  40     "WG Web:  <https:/datatracker.ietf.org/wg/netconf/>
  41      WG List: <mailto:netconf@ietf.org>
  42
  43      Author:  Alexander Clemm
  44               <mailto:ludwig@clemm.org>
  45
  46      Author:  Eric Voit
  47               <mailto:evoit@cisco.com>
  48
  49      Author:  Alberto Gonzalez Prieto
  50               <mailto:alberto.gonzalez@microsoft.com>
  51
  52      Author:  Einar Nilsen-Nygaard
  53               <mailto:einarnn@cisco.com>
  54
  55      Author:  Ambika Prasad Tripathy
  56               <mailto:ambtripa@cisco.com>";
  57   description
  58     "This module defines a YANG data model for subscribing to event
  59      records and receiving matching content in notification messages.
  60
  61      The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
  62      NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
  63      'MAY', and 'OPTIONAL' in this document are to be interpreted as
  64      described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
  65      they appear in all capitals, as shown here.
  66
  67      Copyright (c) 2019 IETF Trust and the persons identified as
  68      authors of the code.  All rights reserved.
  69
  70      Redistribution and use in source and binary forms, with or
  71      without modification, is permitted pursuant to, and subject to
  72      the license terms contained in, the Simplified BSD License set
  73      forth in Section 4.c of the IETF Trust's Legal Provisions
  74      Relating to IETF Documents
  75      (https://trustee.ietf.org/license-info).
  76
  77      This version of this YANG module is part of RFC 8639; see the
  78      RFC itself for full legal notices.";
  79
  80   revision 2019-09-09 {
  81     description
  82       "Initial version.";
  83     reference
  84       "RFC 8639: A YANG Data Model for Subscriptions to
  85                  Event Notifications";
  86   }
  87
  88   /*
  89    * FEATURES
  90    */
  91
  92   feature configured {
  93     description
  94       "This feature indicates that configuration of subscriptions is
  95        supported.";
  96   }
  97
  98   feature dscp {
  99     description
 100       "This feature indicates that a publisher supports the ability
 101        to set the Differentiated Services Code Point (DSCP) value in
 102        outgoing packets.";
 103   }
 104
 105   feature encode-json {
 106     description
 107       "This feature indicates that JSON encoding of notification
 108        messages is supported.";
 109   }
 110
 111   feature encode-xml {
 112     description
 113       "This feature indicates that XML encoding of notification
 114        messages is supported.";
 115   }
 116
 117   feature interface-designation {
 118     description
 119       "This feature indicates that a publisher supports sourcing all
 120        receiver interactions for a configured subscription from a
 121        single designated egress interface.";
 122   }
 123
 124   feature qos {
 125     description
 126       "This feature indicates that a publisher supports absolute
 127        dependencies of one subscription's traffic over another
 128        as well as weighted bandwidth sharing between subscriptions.
 129        Both of these are Quality of Service (QoS) features that allow
 130        differentiated treatment of notification messages between a
 131        publisher and a specific receiver.";
 132   }
 133
 134   feature replay {
 135     description
 136       "This feature indicates that historical event record replay is
 137        supported.  With replay, it is possible for past event records
 138        to be streamed in chronological order.";
 139   }
 140
 141   feature subtree {
 142     description
 143       "This feature indicates support for YANG subtree filtering.";
 144     reference
 145       "RFC 6241: Network Configuration Protocol (NETCONF),
 146                  Section 6";
 147   }
 148
 149   feature supports-vrf {
 150     description
 151       "This feature indicates that a publisher supports VRF
 152        configuration for configured subscriptions.  VRF support for
 153        dynamic subscriptions does not require this feature.";
 154     reference
 155       "RFC 8529: YANG Data Model for Network Instances,
 156                  Section 6";
 157   }
 158
 159   feature xpath {
 160     description
 161       "This feature indicates support for XPath filtering.";
 162     reference
 163       "XML Path Language (XPath) Version 1.0
 164        (https://www.w3.org/TR/1999/REC-xpath-19991116)";
 165   }
 166
 167   /*
 168    * EXTENSIONS
 169    */
 170
 171   extension subscription-state-notification {
 172     description
 173       "This statement applies only to notifications.  It indicates
 174        that the notification is a subscription state change
 175        notification.  Therefore, it does not participate in a regular
 176        event stream and does not need to be specifically subscribed
 177        to in order to be received.  This statement can only occur as
 178        a substatement of the YANG 'notification' statement.  This
 179        statement is not for use outside of this YANG module.";
 180   }
 181
 182   /*
 183    * IDENTITIES
 184    */
 185   /* Identities for RPC and notification errors */
 186
 187   identity delete-subscription-error {
 188     description
 189       "Base identity for the problem found while attempting to
 190        fulfill either a 'delete-subscription' RPC request or a
 191        'kill-subscription' RPC request.";
 192   }
 193
 194   identity establish-subscription-error {
 195     description
 196       "Base identity for the problem found while attempting to
 197        fulfill an 'establish-subscription' RPC request.";
 198   }
 199
 200   identity modify-subscription-error {
 201     description
 202       "Base identity for the problem found while attempting to
 203        fulfill a 'modify-subscription' RPC request.";
 204   }
 205
 206   identity subscription-suspended-reason {
 207     description
 208       "Base identity for the problem condition communicated to a
 209        receiver as part of a 'subscription-suspended'
 210        notification.";
 211   }
 212
 213   identity subscription-terminated-reason {
 214     description
 215       "Base identity for the problem condition communicated to a
 216        receiver as part of a 'subscription-terminated'
 217        notification.";
 218   }
 219
 220   identity dscp-unavailable {
 221     base establish-subscription-error;
 222     if-feature "dscp";
 223     description
 224       "The publisher is unable to mark notification messages with
 225        prioritization information in a way that will be respected
 226        during network transit.";
 227   }
 228
 229   identity encoding-unsupported {
 230     base establish-subscription-error;
 231     description
 232       "Unable to encode notification messages in the desired
 233        format.";
 234   }
 235
 236   identity filter-unavailable {
 237     base subscription-terminated-reason;
 238     description
 239       "Referenced filter does not exist.  This means a receiver is
 240        referencing a filter that doesn't exist or to which it
 241        does not have access permissions.";
 242   }
 243
 244   identity filter-unsupported {
 245     base establish-subscription-error;
 246     base modify-subscription-error;
 247     description
 248       "Cannot parse syntax in the filter.  This failure can be from
 249        a syntax error or a syntax too complex to be processed by the
 250        publisher.";
 251   }
 252
 253   identity insufficient-resources {
 254     base establish-subscription-error;
 255     base modify-subscription-error;
 256     base subscription-suspended-reason;
 257     description
 258       "The publisher does not have sufficient resources to support
 259        the requested subscription.  An example might be that
 260        allocated CPU is too limited to generate the desired set of
 261        notification messages.";
 262   }
 263
 264   identity no-such-subscription {
 265     base modify-subscription-error;
 266     base delete-subscription-error;
 267     base subscription-terminated-reason;
 268     description
 269       "Referenced subscription doesn't exist.  This may be as a
 270        result of a nonexistent subscription ID, an ID that belongs to
 271        another subscriber, or an ID for a configured subscription.";
 272   }
 273
 274   identity replay-unsupported {
 275     base establish-subscription-error;
 276     if-feature "replay";
 277     description
 278       "Replay cannot be performed for this subscription.  This means
 279        the publisher will not provide the requested historic
 280        information from the event stream via replay to this
 281        receiver.";
 282   }
 283
 284   identity stream-unavailable {
 285     base subscription-terminated-reason;
 286     description
 287       "Not a subscribable event stream.  This means the referenced
 288        event stream is not available for subscription by the
 289        receiver.";
 290   }
 291
 292   identity suspension-timeout {
 293     base subscription-terminated-reason;
 294     description
 295       "Termination of a previously suspended subscription.  The
 296        publisher has eliminated the subscription, as it exceeded a
 297        time limit for suspension.";
 298   }
 299
 300   identity unsupportable-volume {
 301     base subscription-suspended-reason;
 302     description
 303       "The publisher does not have the network bandwidth needed to
 304        get the volume of generated information intended for a
 305        receiver.";
 306   }
 307
 308   /* Identities for encodings */
 309
 310   identity configurable-encoding {
 311     description
 312       "If a transport identity derives from this identity, it means
 313        that it supports configurable encodings.  An example of a
 314        configurable encoding might be a new identity such as
 315        'encode-cbor'.  Such an identity could use
 316        'configurable-encoding' as its base.  This would allow a
 317        dynamic subscription encoded in JSON (RFC 8259) to request
 318        that notification messages be encoded via the Concise Binary
 319        Object Representation (CBOR) (RFC 7049).  Further details for
 320        any specific configurable encoding would be explored in a
 321        transport document based on this specification.";
 322     reference
 323       "RFC 8259: The JavaScript Object Notation (JSON) Data
 324                  Interchange Format
 325        RFC 7049: Concise Binary Object Representation (CBOR)";
 326   }
 327
 328   identity encoding {
 329     description
 330       "Base identity to represent data encodings.";
 331   }
 332
 333   identity encode-xml {
 334     base encoding;
 335     if-feature "encode-xml";
 336     description
 337       "Encode data using XML as described in RFC 7950.";
 338     reference
 339       "RFC 7950: The YANG 1.1 Data Modeling Language";
 340   }
 341
 342   identity encode-json {
 343     base encoding;
 344     if-feature "encode-json";
 345     description
 346       "Encode data using JSON as described in RFC 7951.";
 347     reference
 348       "RFC 7951: JSON Encoding of Data Modeled with YANG";
 349   }
 350
 351   /* Identities for transports */
 352
 353   identity transport {
 354     description
 355       "An identity that represents the underlying mechanism for
 356        passing notification messages.";
 357   }
 358
 359   /*
 360    * TYPEDEFs
 361    */
 362
 363   typedef encoding {
 364     type identityref {
 365       base encoding;
 366     }
 367     description
 368       "Specifies a data encoding, e.g., for a data subscription.";
 369   }
 370
 371   typedef stream-filter-ref {
 372     type leafref {
 373       path "/sn:filters/sn:stream-filter/sn:name";
 374     }
 375     description
 376       "This type is used to reference an event stream filter.";
 377   }
 378
 379   typedef stream-ref {
 380     type leafref {
 381       path "/sn:streams/sn:stream/sn:name";
 382     }
 383     description
 384       "This type is used to reference a system-provided
 385        event stream.";
 386   }
 387
 388   typedef subscription-id {
 389     type uint32;
 390     description
 391       "A type for subscription identifiers.";
 392   }
 393
 394   typedef transport {
 395     type identityref {
 396       base transport;
 397     }
 398     description
 399       "Specifies the transport used to send notification messages
 400        to a receiver.";
 401   }
 402
 403   /*
 404    * GROUPINGS
 405    */
 406
 407   grouping stream-filter-elements {
 408     description
 409       "This grouping defines the base for filters applied to event
 410        streams.";
 411     choice filter-spec {
 412       description
 413         "The content filter specification for this request.";
 414       anydata stream-subtree-filter {
 415         if-feature "subtree";
 416         description
 417           "Event stream evaluation criteria encoded in the syntax of
 418            a subtree filter as defined in RFC 6241, Section 6.
 419
 420            The subtree filter is applied to the representation of
 421            individual, delineated event records as contained in the
 422            event stream.
 423
 424            If the subtree filter returns a non-empty node set, the
 425            filter matches the event record, and the event record is
 426            included in the notification message sent to the
 427            receivers.";
 428         reference
 429           "RFC 6241: Network Configuration Protocol (NETCONF),
 430                      Section 6";
 431       }
 432       leaf stream-xpath-filter {
 433         if-feature "xpath";
 434         type yang:xpath1.0;
 435         description
 436           "Event stream evaluation criteria encoded in the syntax of
 437            an XPath 1.0 expression.
 438
 439            The XPath expression is evaluated on the representation of
 440            individual, delineated event records as contained in
 441            the event stream.
 442
 443            The result of the XPath expression is converted to a
 444            boolean value using the standard XPath 1.0 rules.  If the
 445            boolean value is 'true', the filter matches the event
 446            record, and the event record is included in the
 447            notification message sent to the receivers.
 448
 449            The expression is evaluated in the following XPath
 450            context:
 451
 452               o  The set of namespace declarations is the set of
 453                  prefix and namespace pairs for all YANG modules
 454                  implemented by the server, where the prefix is the
 455                  YANG module name and the namespace is as defined by
 456                  the 'namespace' statement in the YANG module.
 457
 458                  If the leaf is encoded in XML, all namespace
 459                  declarations in scope on the 'stream-xpath-filter'
 460                  leaf element are added to the set of namespace
 461                  declarations.  If a prefix found in the XML is
 462                  already present in the set of namespace
 463                  declarations, the namespace in the XML is used.
 464
 465               o  The set of variable bindings is empty.
 466
 467               o  The function library is comprised of the core
 468                  function library and the XPath functions defined in
 469                  Section 10 in RFC 7950.
 470
 471               o  The context node is the root node.";
 472         reference
 473           "XML Path Language (XPath) Version 1.0
 474            (https://www.w3.org/TR/1999/REC-xpath-19991116)
 475            RFC 7950: The YANG 1.1 Data Modeling Language,
 476                      Section 10";
 477       }
 478     }
 479   }
 480
 481   grouping update-qos {
 482     description
 483       "This grouping describes QoS information concerning a
 484        subscription.  This information is passed to lower layers
 485        for transport prioritization and treatment.";
 486     leaf dscp {
 487       if-feature "dscp";
 488       type inet:dscp;
 489       default "0";
 490       description
 491         "The desired network transport priority level.  This is the
 492          priority set on notification messages encapsulating the
 493          results of the subscription.  This transport priority is
 494          shared for all receivers of a given subscription.";
 495     }
 496     leaf weighting {
 497       if-feature "qos";
 498       type uint8 {
 499         range "0 .. 255";
 500       }
 501       description
 502         "Relative weighting for a subscription.  Larger weights get
 503          more resources.  Allows an underlying transport layer to
 504          perform informed load-balance allocations between various
 505          subscriptions.";
 506       reference
 507         "RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2),
 508                    Section 5.3.2";
 509     }
 510     leaf dependency {
 511       if-feature "qos";
 512       type subscription-id;
 513       description
 514         "Provides the 'subscription-id' of a parent subscription.
 515          The parent subscription has absolute precedence should
 516          that parent have push updates ready to egress the publisher.
 517          In other words, there should be no streaming of objects from
 518          the current subscription if the parent has something ready
 519          to push.
 520
 521          If a dependency is asserted via configuration or via an RPC
 522          but the referenced 'subscription-id' does not exist, the
 523          dependency is silently discarded.  If a referenced
 524          subscription is deleted, this dependency is removed.";
 525       reference
 526         "RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2),
 527                    Section 5.3.1";
 528     }
 529   }
 530
 531   grouping subscription-policy-modifiable {
 532     description
 533       "This grouping describes all objects that may be changed
 534        in a subscription.";
 535     choice target {
 536       mandatory true;
 537       description
 538         "Identifies the source of information against which a
 539          subscription is being applied as well as specifics on the
 540          subset of information desired from that source.";
 541       case stream {
 542         choice stream-filter {
 543           description
 544             "An event stream filter can be applied to a subscription.
 545              That filter will either come referenced from a global
 546              list or be provided in the subscription itself.";
 547           case by-reference {
 548             description
 549               "Apply a filter that has been configured separately.";
 550             leaf stream-filter-name {
 551               type stream-filter-ref;
 552               mandatory true;
 553               description
 554                 "References an existing event stream filter that is
 555                  to be applied to an event stream for the
 556                  subscription.";
 557             }
 558           }
 559           case within-subscription {
 560             description
 561               "A local definition allows a filter to have the same
 562                lifecycle as the subscription.";
 563             uses stream-filter-elements;
 564           }
 565         }
 566       }
 567     }
 568     leaf stop-time {
 569       type yang:date-and-time;
 570       description
 571         "Identifies a time after which notification messages for a
 572          subscription should not be sent.  If 'stop-time' is not
 573          present, the notification messages will continue until the
 574          subscription is terminated.  If 'replay-start-time' exists,
 575          'stop-time' must be for a subsequent time.  If
 576          'replay-start-time' doesn't exist, 'stop-time', when
 577          established, must be for a future time.";
 578     }
 579   }
 580
 581   grouping subscription-policy-dynamic {
 582     description
 583       "This grouping describes the only information concerning a
 584        subscription that can be passed over the RPCs defined in this
 585        data model.";
 586     uses subscription-policy-modifiable {
 587       augment "target/stream" {
 588         description
 589           "Adds additional objects that can be modified by an RPC.";
 590         leaf stream {
 591           type stream-ref {
 592             require-instance false;
 593           }
 594           mandatory true;
 595           description
 596             "Indicates the event stream to be considered for
 597              this subscription.";
 598         }
 599         leaf replay-start-time {
 600           if-feature "replay";
 601           type yang:date-and-time;
 602           config false;
 603           description
 604             "Used to trigger the 'replay' feature for a dynamic
 605              subscription, where event records that are selected
 606              need to be at or after the specified starting time.  If
 607              'replay-start-time' is not present, this is not a replay
 608              subscription and event record push should start
 609              immediately.  It is never valid to specify start times
 610              that are later than or equal to the current time.";
 611         }
 612       }
 613     }
 614     uses update-qos;
 615   }
 616
 617   grouping subscription-policy {
 618     description
 619       "This grouping describes the full set of policy information
 620        concerning both dynamic and configured subscriptions, with the
 621        exclusion of both receivers and networking information
 622        specific to the publisher, such as what interface should be
 623        used to transmit notification messages.";
 624     uses subscription-policy-dynamic;
 625     leaf transport {
 626       if-feature "configured";
 627       type transport;
 628       description
 629         "For a configured subscription, this leaf specifies the
 630          transport used to deliver messages destined for all
 631          receivers of that subscription.";
 632     }
 633     leaf encoding {
 634       when 'not(../transport) or derived-from(../transport,
 635       "sn:configurable-encoding")';
 636       type encoding;
 637       description
 638         "The type of encoding for notification messages.  For a
 639          dynamic subscription, if not included as part of an
 640          'establish-subscription' RPC, the encoding will be populated
 641          with the encoding used by that RPC.  For a configured
 642          subscription, if not explicitly configured, the encoding
 643          will be the default encoding for an underlying transport.";
 644     }
 645     leaf purpose {
 646       if-feature "configured";
 647       type string;
 648       description
 649         "Open text allowing a configuring entity to embed the
 650          originator or other specifics of this subscription.";
 651     }
 652   }
 653
 654   /*
 655    * RPCs
 656    */
 657
 658   rpc establish-subscription {
 659     description
 660       "This RPC allows a subscriber to create (and possibly
 661        negotiate) a subscription on its own behalf.  If successful,
 662        the subscription remains in effect for the duration of the
 663        subscriber's association with the publisher or until the
 664        subscription is terminated.  If an error occurs or the
 665        publisher cannot meet the terms of a subscription, an RPC
 666        error is returned, and the subscription is not created.
 667        In that case, the RPC reply's 'error-info' MAY include
 668        suggested parameter settings that would have a higher
 669        likelihood of succeeding in a subsequent
 670        'establish-subscription' request.";
 671     input {
 672       uses subscription-policy-dynamic;
 673       leaf encoding {
 674         type encoding;
 675         description
 676           "The type of encoding for the subscribed data.  If not
 677            included as part of the RPC, the encoding MUST be set by
 678            the publisher to be the encoding used by this RPC.";
 679       }
 680     }
 681     output {
 682       leaf id {
 683         type subscription-id;
 684         mandatory true;
 685         description
 686           "Identifier used for this subscription.";
 687       }
 688       leaf replay-start-time-revision {
 689         if-feature "replay";
 690         type yang:date-and-time;
 691         description
 692           "If a replay has been requested, this object represents
 693            the earliest time covered by the event buffer for the
 694            requested event stream.  The value of this object is the
 695            'replay-log-aged-time' if it exists.  Otherwise, it is
 696            the 'replay-log-creation-time'.  All buffered event
 697            records after this time will be replayed to a receiver.
 698            This object will only be sent if the starting time has
 699            been revised to be later than the time requested by the
 700            subscriber.";
 701       }
 702     }
 703   }
 704
 705   rc:yang-data establish-subscription-stream-error-info {
 706     container establish-subscription-stream-error-info {
 707       description
 708         "If any 'establish-subscription' RPC parameters are
 709          unsupportable against the event stream, a subscription
 710          is not created and the RPC error response MUST indicate the
 711          reason why the subscription failed to be created.  This
 712          yang-data MAY be inserted as structured data in a
 713          subscription's RPC error response to indicate the reason for
 714          the failure.  This yang-data MUST be inserted if hints are
 715          to be provided back to the subscriber.";
 716       leaf reason {
 717         type identityref {
 718           base establish-subscription-error;
 719         }
 720         description
 721           "Indicates the reason why the subscription has failed to
 722            be created to a targeted event stream.";
 723       }
 724       leaf filter-failure-hint {
 725         type string;
 726         description
 727           "Information describing where and/or why a provided
 728            filter was unsupportable for a subscription.  The
 729            syntax and semantics of this hint are
 730            implementation specific.";
 731       }
 732     }
 733   }
 734
 735   rpc modify-subscription {
 736     description
 737       "This RPC allows a subscriber to modify a dynamic
 738        subscription's parameters.  If successful, the changed
 739        subscription parameters remain in effect for the duration of
 740        the subscription, until the subscription is again modified, or
 741        until the subscription is terminated.  In the case of an error
 742        or an inability to meet the modified parameters, the
 743        subscription is not modified and the original subscription
 744        parameters remain in effect.  In that case, the RPC error MAY
 745        include 'error-info' suggested parameter hints that would have
 746        a high likelihood of succeeding in a subsequent
 747        'modify-subscription' request.  A successful
 748        'modify-subscription' will return a suspended subscription to
 749        the 'active' state.";
 750     input {
 751       leaf id {
 752         type subscription-id;
 753         mandatory true;
 754         description
 755           "Identifier to use for this subscription.";
 756       }
 757       uses subscription-policy-modifiable;
 758     }
 759   }
 760
 761   rc:yang-data modify-subscription-stream-error-info {
 762     container modify-subscription-stream-error-info {
 763       description
 764         "This yang-data MAY be provided as part of a subscription's
 765          RPC error response when there is a failure of a
 766          'modify-subscription' RPC that has been made against an
 767          event stream.  This yang-data MUST be used if hints are to
 768          be provided back to the subscriber.";
 769       leaf reason {
 770         type identityref {
 771           base modify-subscription-error;
 772         }
 773         description
 774           "Information in a 'modify-subscription' RPC error response
 775            that indicates the reason why the subscription to an event
 776            stream has failed to be modified.";
 777       }
 778       leaf filter-failure-hint {
 779         type string;
 780         description
 781           "Information describing where and/or why a provided
 782            filter was unsupportable for a subscription.  The syntax
 783            and semantics of this hint are
 784            implementation specific.";
 785       }
 786     }
 787   }
 788
 789   rpc delete-subscription {
 790     description
 791       "This RPC allows a subscriber to delete a subscription that
 792        was previously created by that same subscriber using the
 793        'establish-subscription' RPC.
 794
 795        If an error occurs, the server replies with an 'rpc-error'
 796        where the 'error-info' field MAY contain a
 797        'delete-subscription-error-info' structure.";
 798     input {
 799       leaf id {
 800         type subscription-id;
 801         mandatory true;
 802         description
 803           "Identifier of the subscription that is to be deleted.
 804            Only subscriptions that were created using
 805            'establish-subscription' from the same origin as this RPC
 806            can be deleted via this RPC.";
 807       }
 808     }
 809   }
 810
 811   rpc kill-subscription {
 812     nacm:default-deny-all;
 813     description
 814       "This RPC allows an operator to delete a dynamic subscription
 815        without restrictions on the originating subscriber or
 816        underlying transport session.
 817
 818        If an error occurs, the server replies with an 'rpc-error'
 819        where the 'error-info' field MAY contain a
 820        'delete-subscription-error-info' structure.";
 821     input {
 822       leaf id {
 823         type subscription-id;
 824         mandatory true;
 825         description
 826           "Identifier of the subscription that is to be deleted.
 827            Only subscriptions that were created using
 828            'establish-subscription' can be deleted via this RPC.";
 829       }
 830     }
 831   }
 832
 833   rc:yang-data delete-subscription-error-info {
 834     container delete-subscription-error-info {
 835       description
 836         "If a 'delete-subscription' RPC or a 'kill-subscription' RPC
 837          fails, the subscription is not deleted and the RPC error
 838          response MUST indicate the reason for this failure.  This
 839          yang-data MAY be inserted as structured data in a
 840          subscription's RPC error response to indicate the reason
 841          for the failure.";
 842       leaf reason {
 843         type identityref {
 844           base delete-subscription-error;
 845         }
 846         mandatory true;
 847         description
 848           "Indicates the reason why the subscription has failed to be
 849            deleted.";
 850       }
 851     }
 852   }
 853
 854   /*
 855    * NOTIFICATIONS
 856    */
 857
 858   notification replay-completed {
 859     sn:subscription-state-notification;
 860     if-feature "replay";
 861     description
 862       "This notification is sent to indicate that all of the replay
 863        notifications have been sent.";
 864     leaf id {
 865       type subscription-id;
 866       mandatory true;
 867       description
 868         "This references the affected subscription.";
 869     }
 870   }
 871
 872   notification subscription-completed {
 873     sn:subscription-state-notification;
 874     if-feature "configured";
 875     description
 876       "This notification is sent to indicate that a subscription has
 877        finished passing event records, as the 'stop-time' has been
 878        reached.";
 879     leaf id {
 880       type subscription-id;
 881       mandatory true;
 882       description
 883         "This references the gracefully completed subscription.";
 884     }
 885   }
 886
 887   notification subscription-modified {
 888     sn:subscription-state-notification;
 889     description
 890       "This notification indicates that a subscription has been
 891        modified.  Notification messages sent from this point on will
 892        conform to the modified terms of the subscription.  For
 893        completeness, this subscription state change notification
 894        includes both modified and unmodified aspects of a
 895        subscription.";
 896     leaf id {
 897       type subscription-id;
 898       mandatory true;
 899       description
 900         "This references the affected subscription.";
 901     }
 902     uses subscription-policy {
 903       refine "target/stream/stream-filter/within-subscription" {
 904         description
 905           "Filter applied to the subscription.  If the
 906            'stream-filter-name' is populated, the filter in the
 907            subscription came from the 'filters' container.
 908            Otherwise, it is populated in-line as part of the
 909            subscription.";
 910       }
 911     }
 912   }
 913
 914   notification subscription-resumed {
 915     sn:subscription-state-notification;
 916     description
 917       "This notification indicates that a subscription that had
 918        previously been suspended has resumed.  Notifications will
 919        once again be sent.  In addition, a 'subscription-resumed'
 920        indicates that no modification of parameters has occurred
 921        since the last time event records have been sent.";
 922     leaf id {
 923       type subscription-id;
 924       mandatory true;
 925       description
 926         "This references the affected subscription.";
 927     }
 928   }
 929
 930   notification subscription-started {
 931     sn:subscription-state-notification;
 932     if-feature "configured";
 933     description
 934       "This notification indicates that a subscription has started
 935        and notifications will now be sent.";
 936     leaf id {
 937       type subscription-id;
 938       mandatory true;
 939       description
 940         "This references the affected subscription.";
 941     }
 942     uses subscription-policy {
 943       refine "target/stream/replay-start-time" {
 944         description
 945           "Indicates the time that a replay is using for the
 946            streaming of buffered event records.  This will be
 947            populated with the most recent of the following:
 948            the event time of the previous event record sent to a
 949            receiver, the 'replay-log-creation-time', the
 950            'replay-log-aged-time', or the most recent publisher
 951            boot time.";
 952       }
 953       refine "target/stream/stream-filter/within-subscription" {
 954         description
 955           "Filter applied to the subscription.  If the
 956            'stream-filter-name' is populated, the filter in the
 957            subscription came from the 'filters' container.
 958            Otherwise, it is populated in-line as part of the
 959            subscription.";
 960       }
 961       augment "target/stream" {
 962         description
 963           "This augmentation adds additional parameters specific to a
 964            'subscription-started' notification.";
 965         leaf replay-previous-event-time {
 966           when '../replay-start-time';
 967           if-feature "replay";
 968           type yang:date-and-time;
 969           description
 970             "If there is at least one event in the replay buffer
 971              prior to 'replay-start-time', this gives the time of
 972              the event generated immediately prior to the
 973              'replay-start-time'.
 974
 975              If a receiver previously received event records for
 976              this configured subscription, it can compare this time
 977              to the last event record previously received.  If the
 978              two are not the same (perhaps due to a reboot), then a
 979              dynamic replay can be initiated to acquire any missing
 980              event records.";
 981         }
 982       }
 983     }
 984   }
 985
 986   notification subscription-suspended {
 987     sn:subscription-state-notification;
 988     description
 989       "This notification indicates that a suspension of the
 990        subscription by the publisher has occurred.  No further
 991        notifications will be sent until the subscription resumes.
 992        This notification shall only be sent to receivers of a
 993        subscription; it does not constitute a general-purpose
 994        notification.";
 995     leaf id {
 996       type subscription-id;
 997       mandatory true;
 998       description
 999         "This references the affected subscription.";
1000     }
1001     leaf reason {
1002       type identityref {
1003         base subscription-suspended-reason;
1004       }
1005       mandatory true;
1006       description
1007         "Identifies the condition that resulted in the suspension.";
1008     }
1009   }
1010
1011   notification subscription-terminated {
1012     sn:subscription-state-notification;
1013     description
1014       "This notification indicates that a subscription has been
1015        terminated.";
1016     leaf id {
1017       type subscription-id;
1018       mandatory true;
1019       description
1020         "This references the affected subscription.";
1021     }
1022     leaf reason {
1023       type identityref {
1024         base subscription-terminated-reason;
1025       }
1026       mandatory true;
1027       description
1028         "Identifies the condition that resulted in the termination.";
1029     }
1030   }
1031
1032   /*
1033    * DATA NODES
1034    */
1035
1036   container streams {
1037     config false;
1038     description
1039       "Contains information on the built-in event streams provided by
1040        the publisher.";
1041     list stream {
1042       key "name";
1043       description
1044         "Identifies the built-in event streams that are supported by
1045          the publisher.";
1046       leaf name {
1047         type string;
1048         description
1049           "A handle for a system-provided event stream made up of a
1050            sequential set of event records, each of which is
1051            characterized by its own domain and semantics.";
1052       }
1053       leaf description {
1054         type string;
1055         description
1056           "A description of the event stream, including such
1057            information as the type of event records that are
1058            available in this event stream.";
1059       }
1060       leaf replay-support {
1061         if-feature "replay";
1062         type empty;
1063         description
1064           "Indicates that event record replay is available on this
1065            event stream.";
1066       }
1067       leaf replay-log-creation-time {
1068         when '../replay-support';
1069         if-feature "replay";
1070         type yang:date-and-time;
1071         mandatory true;
1072         description
1073           "The timestamp of the creation of the log used to support
1074            the replay function on this event stream.  This time
1075            might be earlier than the earliest available information
1076            contained in the log.  This object is updated if the log
1077            resets for some reason.";
1078       }
1079       leaf replay-log-aged-time {
1080         when '../replay-support';
1081         if-feature "replay";
1082         type yang:date-and-time;
1083         description
1084           "The timestamp associated with the last event record that
1085            has been aged out of the log.  This timestamp identifies
1086            how far back in history this replay log extends, if it
1087            doesn't extend back to the 'replay-log-creation-time'.
1088            This object MUST be present if replay is supported and any
1089            event records have been aged out of the log.";
1090       }
1091     }
1092   }
1093   container filters {
1094     description
1095       "Contains a list of configurable filters that can be applied to
1096        subscriptions.  This facilitates the reuse of complex filters
1097        once defined.";
1098     list stream-filter {
1099       key "name";
1100       description
1101         "A list of preconfigured filters that can be applied to
1102          subscriptions.";
1103       leaf name {
1104         type string;
1105         description
1106           "A name to differentiate between filters.";
1107       }
1108       uses stream-filter-elements;
1109     }
1110   }
1111   container subscriptions {
1112     description
1113       "Contains the list of currently active subscriptions, i.e.,
1114        subscriptions that are currently in effect, used for
1115        subscription management and monitoring purposes.  This
1116        includes subscriptions that have been set up via
1117        RPC primitives as well as subscriptions that have been
1118        established via configuration.";
1119     list subscription {
1120       key "id";
1121       description
1122         "The identity and specific parameters of a subscription.
1123          Subscriptions in this list can be created using a control
1124          channel or RPC or can be established through configuration.
1125
1126          If the 'kill-subscription' RPC or configuration operations
1127          are used to delete a subscription, a
1128          'subscription-terminated' message is sent to any active or
1129          suspended receivers.";
1130       leaf id {
1131         type subscription-id;
1132         description
1133           "Identifier of a subscription; unique in a given
1134            publisher.";
1135       }
1136       uses subscription-policy {
1137         refine "target/stream/stream" {
1138           description
1139             "Indicates the event stream to be considered for this
1140              subscription.  If an event stream has been removed
1141              and can no longer be referenced by an active
1142              subscription, send a 'subscription-terminated'
1143              notification with 'stream-unavailable' as the reason.
1144              If a configured subscription refers to a nonexistent
1145              event stream, move that subscription to the
1146              'invalid' state.";
1147         }
1148         refine "transport" {
1149           description
1150             "For a configured subscription, this leaf specifies the
1151              transport used to deliver messages destined for all
1152              receivers of that subscription.  This object is
1153              mandatory for subscriptions in the configuration
1154              datastore.  This object (1) is not mandatory for dynamic
1155              subscriptions in the operational state datastore and
1156              (2) should not be present for other types of dynamic
1157              subscriptions.";
1158         }
1159         augment "target/stream" {
1160           description
1161             "Enables objects to be added to a configured stream
1162              subscription.";
1163           leaf configured-replay {
1164             if-feature "configured";
1165             if-feature "replay";
1166             type empty;
1167             description
1168               "The presence of this leaf indicates that replay for
1169                the configured subscription should start at the
1170                earliest time in the event log or at the publisher
1171                boot time, whichever is later.";
1172           }
1173         }
1174       }
1175       choice notification-message-origin {
1176         if-feature "configured";
1177         description
1178           "Identifies the egress interface on the publisher
1179            from which notification messages are to be sent.";
1180         case interface-originated {
1181           description
1182             "When notification messages are to egress a specific,
1183              designated interface on the publisher.";
1184           leaf source-interface {
1185             if-feature "interface-designation";
1186             type if:interface-ref;
1187             description
1188               "References the interface for notification messages.";
1189           }
1190         }
1191         case address-originated {
1192           description
1193             "When notification messages are to depart from a
1194              publisher using a specific originating address and/or
1195              routing context information.";
1196           leaf source-vrf {
1197             if-feature "supports-vrf";
1198             type leafref {
1199               path "/ni:network-instances/ni:network-instance/ni:name";
1200             }
1201             description
1202               "VRF from which notification messages should egress a
1203                publisher.";
1204           }
1205           leaf source-address {
1206             type inet:ip-address-no-zone;
1207             description
1208               "The source address for the notification messages.
1209                If a source VRF exists but this object doesn't, a
1210                publisher's default address for that VRF must
1211                be used.";
1212           }
1213         }
1214       }
1215       leaf configured-subscription-state {
1216         if-feature "configured";
1217         type enumeration {
1218           enum valid {
1219             value 1;
1220             description
1221               "The subscription is supportable with its current
1222                parameters.";
1223           }
1224           enum invalid {
1225             value 2;
1226             description
1227               "The subscription as a whole is unsupportable with its
1228                current parameters.";
1229           }
1230           enum concluded {
1231             value 3;
1232             description
1233               "A subscription is inactive, as it has hit a
1234                stop time.  It no longer has receivers in the
1235                'active' or 'suspended' state, but the subscription
1236                has not yet been removed from configuration.";
1237           }
1238         }
1239         config false;
1240         description
1241           "The presence of this leaf indicates that the subscription
1242            originated from configuration, not through a control
1243            channel or RPC.  The value indicates the state of the
1244            subscription as established by the publisher.";
1245       }
1246       container receivers {
1247         description
1248           "Set of receivers in a subscription.";
1249         list receiver {
1250           key "name";
1251           min-elements 1;
1252           description
1253             "A host intended as a recipient for the notification
1254              messages of a subscription.  For configured
1255              subscriptions, transport-specific network parameters
1256              (or a leafref to those parameters) may be augmented to a
1257              specific receiver in this list.";
1258           leaf name {
1259             type string;
1260             description
1261               "Identifies a unique receiver for a subscription.";
1262           }
1263           leaf sent-event-records {
1264             type yang:zero-based-counter64;
1265             config false;
1266             description
1267               "The number of event records sent to the receiver.  The
1268                count is initialized when a dynamic subscription is
1269                established or when a configured receiver
1270                transitions to the 'valid' state.";
1271           }
1272           leaf excluded-event-records {
1273             type yang:zero-based-counter64;
1274             config false;
1275             description
1276               "The number of event records explicitly removed via
1277                either an event stream filter or an access control
1278                filter so that they are not passed to a receiver.
1279                This count is set to zero each time
1280                'sent-event-records' is initialized.";
1281           }
1282           leaf state {
1283             type enumeration {
1284               enum active {
1285                 value 1;
1286                 description
1287                   "The receiver is currently being sent any
1288                    applicable notification messages for the
1289                    subscription.";
1290               }
1291               enum suspended {
1292                 value 2;
1293                 description
1294                   "The receiver state is 'suspended', so the
1295                    publisher is currently unable to provide
1296                    notification messages for the subscription.";
1297               }
1298               enum connecting {
1299                 value 3;
1300                 if-feature "configured";
1301                 description
1302                   "A subscription has been configured, but a
1303                    'subscription-started' subscription state change
1304                    notification needs to be successfully received
1305                    before notification messages are sent.
1306
1307                    If the 'reset' action is invoked for a receiver of
1308                    an active configured subscription, the state
1309                    must be moved to 'connecting'.";
1310               }
1311               enum disconnected {
1312                 value 4;
1313                 if-feature "configured";
1314                 description
1315                   "A subscription has failed to send a
1316                    'subscription-started' state change to the
1317                    receiver.  Additional connection attempts are not
1318                    currently being made.";
1319               }
1320             }
1321             config false;
1322             mandatory true;
1323             description
1324               "Specifies the state of a subscription from the
1325                perspective of a particular receiver.  With this
1326                information, it is possible to determine whether a
1327                publisher is currently generating notification
1328                messages intended for that receiver.";
1329           }
1330           action reset {
1331             if-feature "configured";
1332             description
1333               "Allows the reset of this configured subscription's
1334                receiver to the 'connecting' state.  This enables the
1335                connection process to be reinitiated.";
1336             output {
1337               leaf time {
1338                 type yang:date-and-time;
1339                 mandatory true;
1340                 description
1341                   "Time at which a publisher returned the receiver to
1342                    the 'connecting' state.";
1343               }
1344             }
1345           }
1346         }
1347       }
1348     }
1349   }
1350 }