module ietf-yang-push {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-yang-push";

    prefix yp;

    import ietf-yang-types {
      prefix yang;
      reference
        "RFC 6991: Common YANG Data Types";


    }
    import ietf-subscribed-notifications {
      prefix sn;
      reference
        "RFC 8639: Subscription to YANG Notifications";


    }
    import ietf-datastores {
      prefix ds;
      reference
        "RFC 8342: Network Management Datastore Architecture (NMDA)";


    }
    import ietf-restconf {
      prefix rc;
      reference
        "RFC 8040: RESTCONF Protocol";


    }
    import ietf-yang-patch {
      prefix ypatch;
      reference
        "RFC 8072: YANG Patch Media Type";


    }

    organization
      "IETF NETCONF (Network Configuration) Working Group";

    contact
      "WG Web:  <https:/datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>

Author:  Alexander Clemm
	 <mailto:ludwig@clemm.org>

Author:  Eric Voit
	 <mailto:evoit@cisco.com>";

    description
      "This module contains YANG specifications for YANG-Push.

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.

Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code.  All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject to
the license terms contained in, the Simplified BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).

This version of this YANG module is part of RFC 8641; see the
RFC itself for full legal notices.";

    revision "2019-09-09" {
      description "Initial revision.";
      reference
        "RFC 8641: Subscriptions to YANG Datastores";

    }

    rc:yang-data "resync-subscription-error";
    rc:yang-data "establish-subscription-datastore-error-info";
    rc:yang-data "modify-subscription-datastore-error-info";

    feature on-change {
      description
        "This feature indicates that on-change triggered subscriptions
are supported.";
    }

    identity resync-subscription-error {
      description
        "Problem found while attempting to fulfill a
'resync-subscription' RPC request.";
    }

    identity cant-exclude {
      base sn:establish-subscription-error;
      description
        "Unable to remove the set of 'excluded-change' parameters.
This means that the publisher is unable to restrict
'push-change-update' notifications to just the change types
requested for this subscription.";
    }

    identity datastore-not-subscribable {
      base sn:establish-subscription-error;sn:subscription-terminated-reason;
      description
        "This is not a subscribable datastore.";
    }

    identity no-such-subscription-resync {
      base resync-subscription-error;
      description
        "The referenced subscription doesn't exist.  This may be as a
result of a nonexistent subscription ID, an ID that belongs to
another subscriber, or an ID for a configured subscription.";
    }

    identity on-change-unsupported {
      base sn:establish-subscription-error;
      description
        "On-change is not supported for any objects that are
selectable by this filter.";
    }

    identity on-change-sync-unsupported {
      base sn:establish-subscription-error;
      description
        "Neither 'sync-on-start' nor resynchronization is supported for
this subscription.  This error will be used for two reasons:
(1) if an 'establish-subscription' RPC includes
'sync-on-start' but the publisher can't support sending a
'push-update' for this subscription for reasons other than
'on-change-unsupported' or 'sync-too-big'
(2) if the 'resync-subscription' RPC is invoked for either an
existing periodic subscription or an on-change subscription
that can't support resynchronization.";
    }

    identity period-unsupported {
      base sn:establish-subscription-error;sn:modify-subscription-error;sn:subscription-suspended-reason;
      description
        "The requested time period or 'dampening-period' is too short.
This can be for both periodic and on-change subscriptions
(with or without dampening).  Hints suggesting alternative
periods may be returned as supplemental information.";
    }

    identity update-too-big {
      base sn:establish-subscription-error;sn:modify-subscription-error;sn:subscription-suspended-reason;
      description
        "Periodic or on-change push update data trees exceed a maximum
size limit.  Hints on the estimated size of what was too big
may be returned as supplemental information.";
    }

    identity sync-too-big {
      base sn:establish-subscription-error;sn:modify-subscription-error;resync-subscription-error;sn:subscription-suspended-reason;
      description
        "The 'sync-on-start' or resynchronization data tree exceeds a
maximum size limit.  Hints on the estimated size of what was
too big may be returned as supplemental information.";
    }

    identity unchanging-selection {
      base sn:establish-subscription-error;sn:modify-subscription-error;sn:subscription-terminated-reason;
      description
        "The selection filter is unlikely to ever select data tree
nodes.  This means that based on the subscriber's current
access rights, the publisher recognizes that the selection
filter is unlikely to ever select data tree nodes that change.
Examples for this might be that the node or subtree doesn't
exist, read access is not permitted for a receiver, or static
objects that only change at reboot have been chosen.";
    }

    typedef change-type {
      type enumeration {
        enum "create" {
          value 0;
          description
            "A change that refers to the creation of a new
datastore node.";
        }
        enum "delete" {
          value 1;
          description
            "A change that refers to the deletion of a
datastore node.";
        }
        enum "insert" {
          value 2;
          description
            "A change that refers to the insertion of a new
user-ordered datastore node.";
        }
        enum "move" {
          value 3;
          description
            "A change that refers to a reordering of the target
datastore node.";
        }
        enum "replace" {
          value 4;
          description
            "A change that refers to a replacement of the target
datastore node's value.";
        }
      }
      description
        "Specifies different types of datastore changes.

This type is based on the edit operations defined for
YANG Patch, with the difference that it is valid for a
receiver to process an update record that performs a
'create' operation on a datastore node the receiver believes
exists or to process a delete on a datastore node the
receiver believes is missing.";
      reference
        "RFC 8072: YANG Patch Media Type, Section 2.5";

    }

    typedef selection-filter-ref {
      type leafref {
        path "/sn:filters/yp:selection-filter/yp:filter-id";
      }
      description
        "This type is used to reference a selection filter.";
    }

    typedef centiseconds {
      type uint32;
      description
        "A period of time, measured in units of 0.01 seconds.";
    }

    rpc resync-subscription {
      if-feature on-change;
      description
        "This RPC allows a subscriber of an active on-change
subscription to request a full push of objects.

A successful invocation results in a 'push-update' of all
datastore nodes that the subscriber is permitted to access.
This RPC can only be invoked on the same session on which the
subscription is currently active.  In the case of an error, a
'resync-subscription-error' is sent as part of an error
response.";
      input {
        leaf id {
          type sn:subscription-id;
          mandatory true;
          description
            "Identifier of the subscription that is to be resynced.";
        }
      }
    }  // rpc resync-subscription

    container resync-subscription-error {
      description
        "If a 'resync-subscription' RPC fails, the subscription is
not resynced and the RPC error response MUST indicate the
reason for this failure.  This yang-data MAY be inserted as
structured data in a subscription's RPC error response
to indicate the reason for the failure.";
      leaf reason {
        type identityref {
          base resync-subscription-error;
        }
        mandatory true;
        description
          "Indicates the reason why the publisher has declined a
request for subscription resynchronization.";
      }

      leaf period-hint {
        type centiseconds;
        description
          "Returned when the requested time period is too short.  This
hint can assert a viable period for either a periodic push
cadence or an on-change dampening interval.";
      }

      leaf filter-failure-hint {
        type string;
        description
          "Information describing where and/or why a provided filter
was unsupportable for a subscription.";
      }

      leaf object-count-estimate {
        type uint32;
        description
          "If there are too many objects that could potentially be
returned by the selection filter, this identifies the
estimate of the number of objects that the filter would
potentially pass.";
      }

      leaf object-count-limit {
        type uint32;
        description
          "If there are too many objects that could be returned by
the selection filter, this identifies the upper limit of
the publisher's ability to service this subscription.";
      }

      leaf kilobytes-estimate {
        type uint32;
        description
          "If the returned information could be beyond the capacity
of the publisher, this would identify the estimated
data size that could result from this selection filter.";
      }

      leaf kilobytes-limit {
        type uint32;
        description
          "If the returned information would be beyond the capacity
of the publisher, this identifies the upper limit of the
publisher's ability to service this subscription.";
      }
    }  // container resync-subscription-error

    container establish-subscription-datastore-error-info {
      description
        "If any 'establish-subscription' RPC parameters are
unsupportable against the datastore, a subscription is not
created and the RPC error response MUST indicate the reason
why the subscription failed to be created.  This yang-data
MAY be inserted as structured data in a subscription's
RPC error response to indicate the reason for the failure.
This yang-data MUST be inserted if hints are to be provided
back to the subscriber.";
      leaf reason {
        type identityref {
          base sn:establish-subscription-error;
        }
        description
          "Indicates the reason why the subscription has failed to
be created to a targeted datastore.";
      }

      leaf period-hint {
        type centiseconds;
        description
          "Returned when the requested time period is too short.  This
hint can assert a viable period for either a periodic push
cadence or an on-change dampening interval.";
      }

      leaf filter-failure-hint {
        type string;
        description
          "Information describing where and/or why a provided filter
was unsupportable for a subscription.";
      }

      leaf object-count-estimate {
        type uint32;
        description
          "If there are too many objects that could potentially be
returned by the selection filter, this identifies the
estimate of the number of objects that the filter would
potentially pass.";
      }

      leaf object-count-limit {
        type uint32;
        description
          "If there are too many objects that could be returned by
the selection filter, this identifies the upper limit of
the publisher's ability to service this subscription.";
      }

      leaf kilobytes-estimate {
        type uint32;
        description
          "If the returned information could be beyond the capacity
of the publisher, this would identify the estimated
data size that could result from this selection filter.";
      }

      leaf kilobytes-limit {
        type uint32;
        description
          "If the returned information would be beyond the capacity
of the publisher, this identifies the upper limit of the
publisher's ability to service this subscription.";
      }
    }  // container establish-subscription-datastore-error-info

    container modify-subscription-datastore-error-info {
      description
        "This yang-data MAY be provided as part of a subscription's
RPC error response when there is a failure of a
'modify-subscription' RPC that has been made against a
datastore.  This yang-data MUST be used if hints are to be
provided back to the subscriber.";
      leaf reason {
        type identityref {
          base sn:modify-subscription-error;
        }
        description
          "Indicates the reason why the subscription has failed to
be modified.";
      }

      leaf period-hint {
        type centiseconds;
        description
          "Returned when the requested time period is too short.  This
hint can assert a viable period for either a periodic push
cadence or an on-change dampening interval.";
      }

      leaf filter-failure-hint {
        type string;
        description
          "Information describing where and/or why a provided filter
was unsupportable for a subscription.";
      }

      leaf object-count-estimate {
        type uint32;
        description
          "If there are too many objects that could potentially be
returned by the selection filter, this identifies the
estimate of the number of objects that the filter would
potentially pass.";
      }

      leaf object-count-limit {
        type uint32;
        description
          "If there are too many objects that could be returned by
the selection filter, this identifies the upper limit of
the publisher's ability to service this subscription.";
      }

      leaf kilobytes-estimate {
        type uint32;
        description
          "If the returned information could be beyond the capacity
of the publisher, this would identify the estimated
data size that could result from this selection filter.";
      }

      leaf kilobytes-limit {
        type uint32;
        description
          "If the returned information would be beyond the capacity
of the publisher, this identifies the upper limit of the
publisher's ability to service this subscription.";
      }
    }  // container modify-subscription-datastore-error-info

    notification push-update {
      description
        "This notification contains a push update that in turn contains
data subscribed to via a subscription.  In the case of a
periodic subscription, this notification is sent for periodic
updates.  It can also be used for synchronization updates of
an on-change subscription.  This notification shall only be
sent to receivers of a subscription.  It does not constitute
a general-purpose notification that would be subscribable as
part of the NETCONF event stream by any receiver.";
      leaf id {
        type sn:subscription-id;
        description
          "This references the subscription that drove the
notification to be sent.";
      }

      anydata datastore-contents {
        description
          "This contains the updated data.  It constitutes a snapshot
at the time of update of the set of data that has been
subscribed to.  The snapshot corresponds to the same
snapshot that would be returned in a corresponding 'get'
operation with the same selection filter parameters
applied.";
      }

      leaf incomplete-update {
        type empty;
        description
          "This is a flag that indicates that not all datastore
nodes subscribed to are included with this update.  In
other words, the publisher has failed to fulfill its full
subscription obligations and, despite its best efforts, is
providing an incomplete set of objects.";
      }
    }  // notification push-update

    notification push-change-update {
      if-feature on-change;
      description
        "This notification contains an on-change push update.  This
notification shall only be sent to the receivers of a
subscription.  It does not constitute a general-purpose
notification that would be subscribable as part of the
NETCONF event stream by any receiver.";
      leaf id {
        type sn:subscription-id;
        description
          "This references the subscription that drove the
notification to be sent.";
      }

      container datastore-changes {
        description
          "This contains the set of datastore changes of the target
datastore, starting at the time of the previous update, per
the terms of the subscription.";
        container yang-patch {
          description
            "Represents a conceptual sequence of datastore edits,
called a patch.  Each patch is given a client-assigned
patch identifier.  Each edit MUST be applied
in ascending order, and all edits MUST be applied.
If any errors occur, then the target datastore MUST NOT
be changed by the YANG Patch operation.

It is possible for a datastore constraint violation to occur
due to any node in the datastore, including nodes not
included in the 'edit' list.  Any validation errors MUST
be reported in the reply message.";
          reference
            "RFC 7950, Section 8.3.";

          leaf patch-id {
            type string;
            mandatory true;
            description
              "An arbitrary string provided by the client to identify
the entire patch.  Error messages returned by the server
that pertain to this patch will be identified by this
'patch-id' value.  A client SHOULD attempt to generate
unique 'patch-id' values to distinguish between
transactions from multiple clients in any audit logs
maintained by the server.";
          }

          leaf comment {
            type string;
            description
              "An arbitrary string provided by the client to describe
the entire patch.  This value SHOULD be present in any
audit logging records generated by the server for the
patch.";
          }

          list edit {
            key "edit-id";
            ordered-by user;
            description
              "Represents one edit within the YANG Patch request message.
The 'edit' list is applied in the following manner:

  - The first edit is conceptually applied to a copy
    of the existing target datastore, e.g., the
    running configuration datastore.
  - Each ascending edit is conceptually applied to
    the result of the previous edit(s).
  - After all edits have been successfully processed,
    the result is validated according to YANG constraints.
  - If successful, the server will attempt to apply
    the result to the target datastore.";
            leaf edit-id {
              type string;
              description
                "Arbitrary string index for the edit.
Error messages returned by the server that pertain
to a specific edit will be identified by this value.";
            }

            leaf operation {
              type enumeration {
                enum "create" {
                  value 0;
                  description
                    "The target data node is created using the supplied
value, only if it does not already exist.  The
'target' leaf identifies the data node to be
created, not the parent data node.";
                }
                enum "delete" {
                  value 1;
                  description
                    "Delete the target node, only if the data resource
currently exists; otherwise, return an error.";
                }
                enum "insert" {
                  value 2;
                  description
                    "Insert the supplied value into a user-ordered
list or leaf-list entry.  The target node must
represent a new data resource.  If the 'where'
parameter is set to 'before' or 'after', then
the 'point' parameter identifies the insertion
point for the target node.";
                }
                enum "merge" {
                  value 3;
                  description
                    "The supplied value is merged with the target data
node.";
                }
                enum "move" {
                  value 4;
                  description
                    "Move the target node.  Reorder a user-ordered
list or leaf-list.  The target node must represent
an existing data resource.  If the 'where' parameter
is set to 'before' or 'after', then the 'point'
parameter identifies the insertion point to move
the target node.";
                }
                enum "replace" {
                  value 5;
                  description
                    "The supplied value is used to replace the target
data node.";
                }
                enum "remove" {
                  value 6;
                  description
                    "Delete the target node if it currently exists.";
                }
              }
              mandatory true;
              description
                "The datastore operation requested for the associated
'edit' entry.";
            }

            leaf target {
              type target-resource-offset;
              mandatory true;
              description
                "Identifies the target data node for the edit
operation.  If the target has the value '/', then
the target data node is the target resource.
The target node MUST identify a data resource,
not the datastore resource.";
            }

            leaf point {
              when
                "(../operation = 'insert' or ../operation = 'move')and (../where = 'before' or ../where = 'after')" {
                description
                  "This leaf only applies for 'insert' or 'move'
operations, before or after an existing entry.";
              }
              type target-resource-offset;
              description
                "The absolute URL path for the data node that is being
used as the insertion point or move point for the
target of this 'edit' entry.";
            }

            leaf where {
              when
                "../operation = 'insert' or ../operation = 'move'" {
                description
                  "This leaf only applies for 'insert' or 'move'
operations.";
              }
              type enumeration {
                enum "before" {
                  value 0;
                  description
                    "Insert or move a data node before the data resource
identified by the 'point' parameter.";
                }
                enum "after" {
                  value 1;
                  description
                    "Insert or move a data node after the data resource
identified by the 'point' parameter.";
                }
                enum "first" {
                  value 2;
                  description
                    "Insert or move a data node so it becomes ordered
as the first entry.";
                }
                enum "last" {
                  value 3;
                  description
                    "Insert or move a data node so it becomes ordered
as the last entry.";
                }
              }
              default "last";
              description
                "Identifies where a data resource will be inserted
or moved.  YANG only allows these operations for
list and leaf-list data nodes that are
'ordered-by user'.";
            }

            anydata value {
              when
                "../operation = 'create' or ../operation = 'merge' or ../operation = 'replace' or ../operation = 'insert'" {
                description
                  "The anydata 'value' is only used for 'create',
'merge', 'replace', and 'insert' operations.";
              }
              description
                "Value used for this edit operation.  The anydata 'value'
contains the target resource associated with the
'target' leaf.

For example, suppose the target node is a YANG container
named foo:

    container foo {
      leaf a { type string; }
      leaf b { type int32; }
    }

The 'value' node contains one instance of foo:

    <value>
       <foo xmlns='example-foo-namespace'>
	  <a>some value</a>
	  <b>42</b>
       </foo>
    </value>
 ";
            }
          }  // list edit
        }  // container yang-patch
      }  // container datastore-changes

      leaf incomplete-update {
        type empty;
        description
          "The presence of this object indicates that not all changes
that have occurred since the last update are included with
this update.  In other words, the publisher has failed to
fulfill its full subscription obligations -- for example,
in cases where it was not able to keep up with a burst of
changes.";
      }
    }  // notification push-change-update
  }  // module ietf-yang-push