module ietf-datastore-push {
namespace "urn:ietf:params:xml:ns:yang:ietf-datastore-push";
prefix yp;
import ietf-inet-types {
prefix inet;
}
import ietf-yang-types {
prefix yang;
}
organization "IETF";
contact
"WG Web:
WG List:
WG Chair: Mahesh Jethanandani
WG Chair: Mehmet Ersue
Editor: Alexander Clemm
Editor: Alberto Gonzalez Prieto
Editor: Eric Voit
";
description
"This module contains conceptual YANG specifications
for datastore push.";
revision 2015-10-15 {
description
"Initial revision.";
reference
"YANG Datastore Push, draft-ietf-netconf-yang-push-00";
}
feature on-change {
description
"This feature indicates that on-change updates are supported.";
}
feature json {
description
"This feature indicates that JSON encoding of push updates is
supported.";
}
identity subscription-stream-status {
description
"Base identity for the status of subscriptions and
datastreams.";
}
identity active {
base subscription-stream-status;
description
"Status is active and healthy.";
}
identity inactive {
base subscription-stream-status;
description
"Status is inactive, for example outside the
interval between start time and stop time.";
}
identity in-error {
base subscription-stream-status;
description
"The status is in error or degraded, meaning that
stream and/or subscription are currently unable to provide
the negotiated updates.";
}
identity subscription-errors {
description
"Base identity for subscription errors.";
}
identity internal-error {
base subscription-errors;
description
"Subscription failures caused by server internal error.";
}
identity no-resources {
base subscription-errors;
description
"Lack of resources, e.g. CPU, memory, bandwidth";
}
identity subscription-deleted {
base subscription-errors;
description
"The subscription was terminated because the subscription
was deleted.";
}
identity other {
base subscription-errors;
description
"Fallback reason - any other reason";
}
identity encodings {
description
"Base identity to represent data encodings";
}
identity encode-xml {
base encodings;
description
"Encode data using XML";
}
identity encode-json {
base encodings;
description
"Encode data using JSON";
}
identity system-streams {
description
"Base identity to represent a conceptual system-provided
datastream of datastore updates with predefined semantics.";
}
identity datastore-push {
base system-streams;
description
"A conceptual datastream consisting of all datastore
updates, including operational and configuration data.";
}
identity operational-push {
base system-streams;
description
"A conceptual datastream consisting of updates of all
operational data.";
}
identity config-push {
base system-streams;
description
"A conceptual datastream consisting of updates of all
configuration data.";
}
identity datastore {
description
"An identity that represents a datastore.";
}
identity running {
base datastore;
description
"Designates the running datastore";
}
identity startup {
base datastore;
description
"Designates the startup datastore";
}
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 string;
description
"This type defines an identifier for a filter.";
}
typedef subtree-filter {
type string;
description
"This type is used to specify the subtree that the
subscription refers to. Its syntax follows the subtree
filter syntax specified for Netconf in RFC 6241,
section 6.";
reference "RFC 6241 section 6";
}
typedef datastore {
type identityref {
base datastore;
}
description
"Used to refer to a datastore, for example, to running";
}
typedef subscription-id {
type string {
length "1 .. max";
}
description
"A client-provided identifier for the subscription.";
}
typedef subscription-term-reason {
type identityref {
base subscription-errors;
}
description
"Reason for a server to terminate a subscription.";
}
typedef subscription-susp-reason {
type identityref {
base subscription-errors;
}
description
"Reason for a server to suspend a subscription.";
}
typedef encoding {
type identityref {
base 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 system-stream {
type identityref {
base system-streams;
}
description
"Specifies a system-provided datastream.";
}
typedef filter-ref {
type leafref {
path "/yp:filters/yp:filter/yp:filter-id";
}
description
"This type is used to reference a yang push filter.";
}
grouping datatree-filter {
description
"This grouping defines filters for a datastore tree.";
choice filter-type {
description
"A filter needs to be a single filter of a given type.
Mixing and matching of multiple filters does not occur
at the level of this grouping.";
case subtree {
description
"Subtree filter";
leaf subtree-filter {
type subtree-filter;
description
"Datastore subtree of interest.";
}
}
case xpath {
description
"XPath filter";
leaf xpath-filter {
type yang:xpath1.0;
description
"Xpath defining the data items of interest.";
}
}
}
}
grouping subscription-info {
description
"This grouping describes basic information concerning a
subscription.";
leaf target-datastore {
type datastore;
default "running";
description
"The datastore that is the target of the subscription.
If not specified, running applies.";
}
leaf stream {
type system-stream;
default "datastore-push";
description
"The name of the stream subscribed to.";
}
leaf encoding {
type encoding;
default "encode-xml";
description
"The type of encoding for the subscribed data.
Default is XML";
}
leaf 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 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.";
}
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;
description
"Elapsed time between notifications.";
}
}
case 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.";
}
}
}
choice filterspec {
description
"Filter can be specified in-line, as part of the
subscription, or configured separately and referenced
here. If no filter is specified, the entire datatree
is of interest.";
case inline {
description
"Filter is defined as part of the subscription.";
uses datatree-filter;
}
case by-reference {
description
"Incorporate a filter that has been configured
separately.";
leaf filter-ref {
type filter-ref;
description
"References the filter to incorporate for the
subscription.";
}
}
}
}
grouping receiver-info {
description
"Defines a reusable snippet that defines the address of the
intended receiver of push updates for a subscription.";
container receiver-address {
description
"This container contains the address information of the
receiver.";
choice push-base-transport {
description
"This choice can be augmented with different options,
depending on the transport underlying the push
transport.";
case tcpudp {
description
"For Netconf and Restconf, TCP is the base transport.";
container tcpudp {
description
"Contains TCP / UDP addressing information";
leaf address {
type inet:host;
description
"The leaf uniquely specifies the address of the
remote host. One of the following must be
specified: an ipv4 address, an ipv6 address,
or a host name.";
}
leaf port {
type inet:port-number;
description
"This leaf specifies the port number used to
deliver messages to the remote server.";
}
}
}
}
}
}
rpc create-subscription {
description
"This RPC allows a subscriber to create a subscription
on its own behalf. If successful, the subscription
remains in effect for the duration of the subscriber's
association with the publisher, or until the subscription
is terminated by virtue of a delete-subscription request.";
input {
uses subscription-info;
}
output {
leaf subscription-id {
type subscription-id;
description
"Identifier used for this subscription.";
}
}
}
rpc modify-subscription {
description
"This RPC allows a subscriber to modify a subscription
that was previously created using create-subscription.
If successful, the subscription
remains in effect for the duration of the subscriber's
association with the publisher, or until the subscription
is terminated by virtue of a delete-subscription request.";
input {
leaf subscription-id {
type subscription-id;
description
"Identifier to use for this subscription.";
}
}
}
rpc delete-subscription {
description
"This RPC allows a subscriber to delete a subscription that
was previously created using create-subscription.";
input {
leaf subscription-id {
type subscription-id;
description
"Identifier of the subscription that is to be deleted.
Only subscriptions that were created using
create-subscription can be deleted via this RPC.";
}
}
}
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 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 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 {
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 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 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.";
}
}
}
}
notification subscription-started {
description
"This notification indicates 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.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
uses subscription-info;
}
notification subscription-suspended {
description
"This notification indicates that a suspension of the
subscription by the server has occurred. No further
datastore updates will be sent until subscription
resumes.
This notification shall only be sent to receivers
of a subscription; it does not constitute a general-purpose
notification.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
leaf reason {
type subscription-susp-reason;
description
"Provides a reason for why the subscription was
suspended.";
}
}
notification subscription-resumed {
description
"This notification indicates that a subscription that had
previously been suspended has resumed. Datastore updates
will once again be sent.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
}
notification subscription-modified {
description
"This notification indicates that a subscription has
been modified. Datastore updates sent from this point
on will conform to the modified terms of the
subscription.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
uses subscription-info;
}
notification subscription-terminated {
description
"This notification indicates that a subscription has been
terminated.";
leaf subscription-id {
type subscription-id;
mandatory true;
description
"This references the affected subscription.";
}
leaf reason {
type subscription-term-reason;
description
"Provides a reason for why the subscription was
terminated.";
}
}
container system-streams {
config false;
description
"This container contains a leaf list of built-in
streams that are provided by the system.";
leaf-list system-stream {
type system-stream;
description
"Identifies a built-in stream that is supported by the
system. Streams are associated with their own identities,
each of which carries a special semantics.";
}
}
container filters {
description
"This container contains a list of configurable filters
that can be applied to subscriptions. This facilitates
the reuse of complex filters once defined.";
list filter {
key "filter-id";
description
"A list of configurable filters that can be applied to
subscriptions.";
leaf filter-id {
type filter-id;
description
"An identifier to differentiate between filters.";
}
uses datatree-filter;
}
}
container subscription-config {
description
"Contains the list of subscriptions that are configured,
as opposed to established via RPC or other means.";
list datastore-push-subscription {
key "subscription-id";
description
"Content of a yang-push subscription.";
leaf subscription-id {
type subscription-id;
description
"Identifier to use for this subscription.";
}
uses subscription-info;
uses receiver-info;
}
}
container subscriptions {
config false;
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. create-subscription, delete-subscription,
and modify-subscription, as well as subscriptions that
have been established via configuration.";
list datastore-push-subscription {
key "subscription-id";
config false;
description
"Content of a yang-push subscription.
Subscriptions can be created using a control channel
or RPC, or be established through configuration.";
leaf subscription-id {
type subscription-id;
description
"Identifier of this subscription.";
}
leaf configured-subscription {
type empty;
description
"The presence of this leaf indicates that the
subscription originated from configuration, not through
a control channel or RPC.";
}
leaf subscription-status {
type identityref {
base subscription-stream-status;
}
description
"The status of the subscription.";
}
uses subscription-info;
uses receiver-info;
}
}
}