module ietf-yang-push {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
prefix yp;
import ietf-inet-types {
prefix inet;
}
import ietf-yang-types {
prefix yang;
}
import ietf-event-notifications {
prefix notif-bis;
}
import ietf-5277-netconf {
prefix notif;
}
organization "IETF";
contact
"WG Web:
WG List:
WG Chair: Mahesh Jethanandani
WG Chair: Mehmet Ersue
Editor: Alexander Clemm
Editor: Eric Voit
Editor: Alberto Gonzalez Prieto
Editor: Ambika Prasad Tripathy
Editor: Einar Nilsen-Nygaard
";
description
"This module contains conceptual YANG specifications
for YANG push.";
revision 2016-06-15 {
description
"First revision to incorporate RFC 5277-bis.";
reference "YANG Datastore Push, draft-ietf-netconf-yang-push-03";
}
feature on-change {
description
"This feature indicates that on-change updates are
supported.";
}
/*
* IDENTITIES
*/
/* Additional errors for subscription operations */
identity error-data-not-authorized {
base notif-bis:error;
description
"No read authorization for a requested data node.";
}
/* Additional types of streams */
identity update-stream {
base notif:stream;
description
"Base identity to represent a conceptual system-provided
datastream of datastore updates with predefined semantics.";
}
identity yang-push {
base update-stream;
description
"A conceptual datastream consisting of all datastore
updates, including operational and configuration data.";
}
identity operational-push {
base update-stream;
description
"A conceptual datastream consisting of updates of all
operational data.";
}
identity config-push {
base update-stream;
description
"A conceptual datastream consisting of updates of all
configuration data.";
}
identity custom-stream {
base update-stream;
description
"A conceptual datastream for datastore
updates with custom updates as defined by a user.";
}
/* Additional transport option */
identity restconf {
base notif-bis:transport;
description
"Restconf notifications as a transport";
}
/*
* TYPE DEFINITIONS
*/
typedef datastore-contents-xml {
type string;
description
"This type is be used to represent datastore contents,
i.e. a set of data nodes with their values, in XML.
The syntax corresponds to the syntax of the data payload
returned in a corresponding Netconf get operation with the
same filter parameters applied.";
reference "RFC 6241 section 7.7";
}
typedef datastore-changes-xml {
type string;
description
"This type is used to represent a set of changes in a
datastore encoded in XML, indicating for datanodes whether
they have been created, deleted, or updated. The syntax
corresponds to the syntax used to when editing a
datastore using the edit-config operation in Netconf.";
reference "RFC 6241 section 7.2";
}
typedef datastore-contents-json {
type string;
description
"This type is be used to represent datastore contents,
i.e. a set of data nodes with their values, in JSON.
The syntax corresponds to the syntax of the data
payload returned in a corresponding RESTCONF get
operation with the same filter parameters applied.";
reference "RESTCONF Protocol";
}
typedef datastore-changes-json {
type string;
description
"This type is used to represent a set of changes in a
datastore encoded in JSON, indicating for datanodes whether
they have been created, deleted, or updated. The syntax
corresponds to the syntax used to patch a datastore
using the yang-patch operation with Restconf.";
reference "draft-ietf-netconf-yang-patch";
}
typedef filter-id {
type uint32;
description
"A type to identify filters which can be associated with a
subscription.";
}
typedef subscription-result {
type identityref {
base notif-bis:subscription-result;
}
description
"The result of a subscription operation";
}
typedef subscription-term-reason {
type identityref {
base notif-bis:subscription-errors;
}
description
"Reason for a server to terminate a subscription.";
}
typedef subscription-susp-reason {
type identityref {
base notif-bis:subscription-errors;
}
description
"Reason for a server to suspend a subscription.";
}
typedef encoding {
type identityref {
base notif-bis:encodings;
}
description
"Specifies a data encoding, e.g. for a data subscription.";
}
typedef change-type {
type enumeration {
enum "create" {
description
"A new data node was created";
}
enum "delete" {
description
"A data node was deleted";
}
enum "modify" {
description
"The value of a data node has changed";
}
}
description
"Specifies different types of changes that may occur
to a datastore.";
}
typedef transport-protocol {
type identityref {
base notif-bis:transport;
}
description
"Specifies transport protocol used to send updates to a
receiver.";
}
typedef push-source {
type enumeration {
enum "interface-originated" {
description
"Pushes will be sent from a specific interface on a
Publisher";
}
enum "address-originated" {
description
"Pushes will be sent from a specific address on a
Publisher";
}
}
description
"Specifies from where objects will be sourced when being pushed
off a publisher.";
}
typedef update-stream {
type identityref {
base update-stream;
}
description
"Specifies a system-provided datastream.";
}
grouping update-filter {
description
"This groupings defines filters for push updates for a datastore
tree. The filters define which updates are of interest in a
push update subscription.
Mixing and matching of multiple filters does not occur
at the level of this grouping.
When a push-update subscription is created, the filter can
be a regular subscription filter, or one of the additional
filters that are defined in this grouping.";
choice update-filter {
description
"Define filters regarding which data nodes to include
in push updates";
case subtree {
description
"Subtree filter.";
anyxml subtree-filter {
description
"Subtree-filter used to specify the data nodes targeted
for subscription within a subtree, or subtrees, of a
conceptual YANG datastore.
It may include additional criteria,
allowing users to receive only updates of a limited
set of data nodes that match those filter criteria.
This will be used to define what
updates to include in a stream of update events, i.e.
to specify for which data nodes update events should be
generated and specific match expressions that objects
need to meet. The syntax follows the subtree filter
syntax specified in RFC 6241, section 6.";
reference "RFC 6241 section 6";
}
}
case xpath {
description
"XPath filter";
leaf xpath-filter {
type yang:xpath1.0;
description
"Xpath defining the data items of interest.";
}
}
}
}
grouping update-policy {
description
"This grouping describes the conditions under which an
update will be sent as part of an update stream.";
choice update-trigger {
description
"Defines necessary conditions for sending an event to
the subscriber.";
case periodic {
description
"The agent is requested to notify periodically the
current values of the datastore or the subset
defined by the filter.";
leaf period {
type yang:timeticks;
mandatory true;
description
"Duraton of time which should occur between periodic
push updates. Where the anchor of a start-time is
available, the push will include the objects and their
values which exist at an exact multiple of timeticks
aligning to this start-time anchor.";
}
}
case on-change {
if-feature "on-change";
description
"The agent is requested to notify changes in
values in the datastore or a subset of it defined
by a filter.";
leaf no-synch-on-start {
type empty;
description
"This leaf acts as a flag that determines behavior at the
start of the subscription. When present,
synchronization of state at the beginning of the
subscription is outside the scope of the subscription.
Only updates about changes that are observed from the
start time, i.e. only push-change-update notifications
are sent.
When absent (default behavior), in order to facilitate
a receiver's synchronization, a full update is sent
when the subscription starts using a push-update
notification, just like in the case of a periodic
subscription. After that, push-change-update
notifications are sent.";
}
leaf dampening-period {
type yang:timeticks;
mandatory true;
description
"Minimum amount of time that needs to have
passed since the last time an update was
provided.";
}
leaf-list excluded-change {
type change-type;
description
"Use to restrict which changes trigger an update.
For example, if modify is excluded, only creation and
deletion of objects is reported.";
}
}
}
}
grouping push-subscription-info {
description
"This grouping describes information concerning a
push subscription that is need in addition to information
already included in notif-bis:subscription-info.";
leaf subscription-start-time {
type yang:date-and-time;
description
"Designates the time at which a subscription is supposed
to start, or immediately, in case the start-time is in
the past. For periodic subscription, the start time also
serves as anchor time from which the time of the next
update is computed. The next update will take place at the
next period interval from the anchor time.
For example, for an anchor time at the top of a minute
and a period interval of a minute, the next update will
be sent at the top of the next minute.";
}
leaf subscription-stop-time {
type yang:date-and-time;
description
"Designates the time at which a subscription will end.
When a subscription reaches its stop time, it will be
automatically deleted. No final push is required unless there
is exact alignment with the end of a periodic subscription
period.";
}
}
grouping subscription-qos {
description
"This grouping describes Quality of Service information
concerning a subscription. This information is passed to lower
layers for transport priortization and treatment";
leaf dscp {
if-feature "notif-bis:configured-subscriptions";
type inet:dscp;
default "0";
description
"The push update's IP packet transport priority.
This is made visible across network hops to receiver.
The transport priority is shared for all receivers of
a given subscription.";
}
leaf subscription-priority {
type uint8;
description
"Relative priority for a subscription. Allows an underlying
transport layer perform informed load balance allocations
between various subscriptions";
}
leaf subscription-dependency {
type string;
description
"Provides the Subscription ID of a parent subscription
without which this subscription should not exist. In
other words, there is no reason to stream these objects
if another subscription is missing.";
}
}
augment "/notif-bis:establish-subscription/notif-bis:input" {
description
"Define additional subscription parameters that apply
specifically to push updates";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:establish-subscription/notif-bis:input/notif-bis:filter-type" {
description
"Add push filters to selection of filter types.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
augment "/notif-bis:establish-subscription/notif-bis:output" {
description
"Allow to return additional subscription parameters that apply
specifically to push updates.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:establish-subscription/notif-bis:output/"+
"notif-bis:result/notif-bis:no-success/notif-bis:filter-type" {
description
"Add push filters to selection of filter types.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
augment "/notif-bis:modify-subscription/notif-bis:input" {
description
"Define additional subscription parameters that apply
specifically to push updates.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:modify-subscription/notif-bis:input/notif-bis:filter-type" {
description
"Add push filters to selection of filter types.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
augment "/notif-bis:modify-subscription/notif-bis:output" {
description
"Allow to retun additional subscription parameters that apply
specifically to push updates.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:modify-subscription/notif-bis:output/"+
"notif-bis:result/notif-bis:no-success/notif-bis:filter-type" {
description
"Add push filters to selection of filter types.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
notification push-update {
description
"This notification contains a periodic push update.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
leaf subscription-id {
type notif-bis:subscription-id;
mandatory true;
description
"This references the subscription because of which the
notification is sent.";
}
leaf time-of-update {
type yang:date-and-time;
description
"This leaf contains the time of the update.";
}
choice encoding {
description
"Distinguish between the proper encoding that was specified
for the subscription";
case encode-xml {
description
"XML encoding";
leaf datastore-contents-xml {
type datastore-contents-xml;
description
"This contains data encoded in XML,
per the subscription.";
}
}
case encode-json {
if-feature "notif-bis:json";
description
"JSON encoding";
leaf datastore-contents-json {
type datastore-contents-json;
description
"This leaf contains data encoded in JSON,
per the subscription.";
}
}
}
}
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.";
leaf subscription-id {
type notif-bis:subscription-id;
mandatory true;
description
"This references the subscription because of which the
notification is sent.";
}
leaf time-of-update {
type yang:date-and-time;
description
"This leaf contains the time of the update, i.e. the
time at which the change was observed.";
}
choice encoding {
description
"Distinguish between the proper encoding that was specified
for the subscription";
case encode-xml {
description
"XML encoding";
leaf datastore-changes-xml {
type datastore-changes-xml;
description
"This contains datastore contents that has changed
since the previous update, per the terms of the
subscription. Changes are encoded analogous to
the syntax of a corresponding Netconf edit-config
operation.";
}
}
case encode-json {
if-feature "notif-bis:json";
description
"JSON encoding";
leaf datastore-changes-yang {
type datastore-changes-json;
description
"This contains datastore contents that has changed
since the previous update, per the terms of the
subscription. Changes are encoded analogous
to the syntax of a corresponding RESTCONF yang-patch
operation.";
}
}
}
}
augment "/notif-bis:subscription-started" {
description
"This augmentation adds push subscription parameters
to the notification that a subscription has
started and data updates are beginning to be sent.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:subscription-started/notif-bis:filter-type" {
description
"This augmentation allows to include additional update filters
options to be included as part of the notification that a
subscription has started.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
augment "/notif-bis:subscription-modified" {
description
"This augmentation adds push subscription parameters
to the notification that a subscription has
been modified.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:subscription-modified/notif-bis:filter-type" {
description
"This augmentation allows to include additional update filters
options to be included as part of the notification that a
subscription has been modified.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
augment "/notif-bis:filters/notif-bis:filter/notif-bis:filter-type" {
description
"This container adds additional update filter options
to the list of configurable filters
that can be applied to subscriptions. This facilitates
the reuse of complex filters once defined.";
case update-filter {
uses update-filter;
}
}
augment "/notif-bis:subscription-config/notif-bis:subscription" {
description
"Contains the list of subscriptions that are configured,
as opposed to established via RPC or other means.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:subscription-config/notif-bis:subscription/notif-bis:filter-type" {
description
"Add push filters to selection of filter types.";
case update-filter {
uses update-filter;
}
}
augment "/notif-bis:subscriptions/notif-bis:subscription" {
description
"Contains the list of currently active subscriptions,
i.e. subscriptions that are currently in effect,
used for subscription management and monitoring purposes.
This includes subscriptions that have been setup via RPC
primitives, e.g. establish-subscription, delete-subscription,
and modify-subscription, as well as subscriptions that
have been established via configuration.";
uses push-subscription-info;
uses update-policy;
uses subscription-qos;
}
augment "/notif-bis:subscriptions/notif-bis:subscription/notif-bis:filter-type" {
description
"Add push filters to selection of filter types.";
case update-filter {
description
"Additional filter options for push subscription.";
uses update-filter;
}
}
}