Support of Versioning in
YANG Notifications SubscriptionSwisscomBinzring 17Zurich8045Switzerlandthomas.graf@swisscom.comHuaweibenoit.claise@huawei.comINSA-LyonLyonFrancealex.huang-feng@insa-lyon.frThis document extends the YANG notifications subscription mechanism
to specify the YANG module semantic version at the subscription. Then, a
new extension with the revision and the semantic version of the YANG
push subscription state change notification is proposed.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
when, and only when,
they appear in all capitals, as shown here.In order to process the received YANG push notification messages
described in section 3.7 of at the YANG push
receiver, a semantic reference to the YANG module and the XPath or
subtree is needed to determine the data types for each field and which
part of the YANG module the metrics are expose from.This specification applies to the YANG push configured subscriptions
defined in Section 2.5 of , where a publisher is
configured to stream notification out of band, as opposed to dynamic
subscriptions defined in Section 2.4 of , where
the subscriber can initiate and modify the subscription dynamically
in-band. In the latter case, the subscriber knows already all the
subscriber YANG-related information, which it has to know in order to
configure the subscription.This semantic reference is available when the subscription is being
establish as described in Section 3.6 of and
being streamed from the publisher to receiver with the subscription
state change notifications described in Section 2.7 of where for each subscription a locally unique
subscription ID described in Section 4.3.2 of
is being issued and streamed as metadata with the notification message
in the YANG push message header.The semantics can change between different YANG module revisions. The
YANG module version statement is specified in Section 7.1.2 of and states that the newer revision needs to be
backward compatible to the previous revision. Section 3.1 of specifies that newer
semantic versions introduced in MAY not be backward compatible to
the previous version when indicated with non-backwards-compatible
keyword.The YANG notifications subscription mechanism defined in does not allow to specify the YANG module revision.
When a network node is upgraded, the subscribed YANG module revision MAY
have updated and might, consequently, break the data processing pipeline
since the YANG push receiver may not be aware of this change.This documents extends the current YANG notifications subscription
mechanism to allow to subscribe to a specific revision or latest YANG
module semantic version to which the YANG module version needs to be
backward compatible to. The subscription state change
"subscription-started" and "subscription-modified" notification messages
are also extended to include the revision and semantic version.The YANG notifications subscription OPTIONALLY can be restricted to
the following YANG module revision for future capabilities:
latest:
Restricts the subscription to the latest YANG module
revision.
revision:
Restricts the subscription to a specific YANG module revision.
Example: "2014-05-08".
latest-compatible-semversion:
Restricts the subscription to the latest compatible YANG module
semantic version referenced to. Example: "2.0.0".
If nothing is specified, latest YANG module version is implied.Besides the Subscription ID and the xpath or sub-tree filter
reference as described in Section 2.7 of , the
following metadata objects are part of a "subscription-started" or
"subscription-modified" subscription state change notification.
revision:
Describes the YANG module revision as specified in Section 7.1.9
of for the related streamed content.
revision-label:
Describes the YANG module semantic version as specified in for the related streamed
content.
provides an
example of a "subscription-modified" subscription state change
notification message with the YANG revision, revision label and
datastore-xpath-filter for tracking the operational status of a single
Ethernet interface (per ). This subscription
state change notification message is encoded XML over the Network Configuration Protocol
(NETCONF) as per .2023-01-03T10:00:00Z1012014-05-081.0.0
/int:interfaces
NETCONF
]]> provides an
example of a JSON encoded, , subscription state
change notification message over HTTPS-based or UDP-based transport for the same
subscription.This YANG module augments the "ietf-yang-push" module with the
revision and revision-label in the "subscription-started" and
"subscription-modified" subscription state change notifications and
the ability to define the "revision" and "revision-label" in the
"establish-subscription" and "modify-subscription" RPCs in the
datastore push subscription.The following is the YANG tree diagram
for the ietf-yang-push-revision YANG moduleThe following is the YANG tree diagram
for the ietf-yang-push-revision augmentation within the
ietf-subscribed-notifications, including the RPCs and
notifications. {subtree}?
| +--:(stream-xpath-filter)
| +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
+--rw subscriptions
+--rw subscription* [id]
+--rw id subscription-id
+--rw (target)
| +--:(stream)
| | +--rw (stream-filter)?
| | | +--:(by-reference)
| | | | +--rw stream-filter-name stream-filter-ref
| | | +--:(within-subscription)
| | | +--rw (filter-spec)?
| | | +--:(stream-subtree-filter)
| | | | +--rw stream-subtree-filter? {subtree}?
| | | +--:(stream-xpath-filter)
| | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
| | +--rw stream stream-ref
| | +--ro replay-start-time? yang:date-and-time {replay}?
| | +--rw configured-replay? empty {configured,replay}?
| +--:(ypm:revision)
| | +--ro ypm:revision rev:revision-date-or-label
| +--:(ypm:revision-label)
| +--rw ypm:revision-label? ysver:version
+--rw stop-time? yang:date-and-time
+--rw dscp? inet:dscp {dscp}?
+--rw weighting? uint8 {qos}?
+--rw dependency? subscription-id {qos}?
+--rw transport? transport {configured}?
+--rw encoding? encoding
+--rw purpose? string {configured}?
+--rw (notification-message-origin)? {configured}?
| +--:(interface-originated)
| | +--rw source-interface? if:interface-ref {interface-designation}?
| +--:(address-originated)
| +--rw source-vrf? -> /ni:network-instances/network-instance/name {supports-vrf}?
| +--rw source-address? inet:ip-address-no-zone
+--ro configured-subscription-state? enumeration {configured}?
+--rw receivers
+--rw receiver* [name]
+--rw name string
+--ro sent-event-records? yang:zero-based-counter64
+--ro excluded-event-records? yang:zero-based-counter64
+--ro state enumeration
+---x reset {configured}?
+--ro output
+--ro time yang:date-and-time
rpcs:
+---x establish-subscription
| +---w input
| | +---w (target)
| | | +--:(stream)
| | | | +---w (stream-filter)?
| | | | | +--:(by-reference)
| | | | | | +---w stream-filter-name stream-filter-ref
| | | | | +--:(within-subscription)
| | | | | +---w (filter-spec)?
| | | | | +--:(stream-subtree-filter)
| | | | | | +---w stream-subtree-filter? {subtree}?
| | | | | +--:(stream-xpath-filter)
| | | | | +---w stream-xpath-filter? yang:xpath1.0 {xpath}?
| | | | +---w stream stream-ref
| | | | +---w replay-start-time? yang:date-and-time {replay}?
| | | +--:(ypm:revision)
| | | | +---w ypm:revision? rev:revision-date-or-label
| | | +--:(ypm:revision-label)
| | | +---w ypm:revision-label? ysver:version
| | +---w stop-time? yang:date-and-time
| | +---w dscp? inet:dscp {dscp}?
| | +---w weighting? uint8 {qos}?
| | +---w dependency? subscription-id {qos}?
| | +---w encoding? encoding
| +--ro output
| +--ro id subscription-id
| +--ro replay-start-time-revision? yang:date-and-time {replay}?
+---x modify-subscription
| +---w input
| +---w id subscription-id
| +---w (target)
| | +--:(stream)
| | | +---w (stream-filter)?
| | | +--:(by-reference)
| | | | +---w stream-filter-name stream-filter-ref
| | | +--:(within-subscription)
| | | +---w (filter-spec)?
| | | +--:(stream-subtree-filter)
| | | | +---w stream-subtree-filter? {subtree}?
| | | +--:(stream-xpath-filter)
| | | +---w stream-xpath-filter? yang:xpath1.0 {xpath}?
| | +--:(ypm:revision)
| | | +---w ypm:revision? rev:revision-date-or-label
| | +--:(ypm:revision-label)
| | +---w ypm:revision-label? ysver:version
| +---w stop-time? yang:date-and-time
+---x delete-subscription
| +---w input
| +---w id subscription-id
+---x kill-subscription
+---w input
+---w id subscription-id
notifications:
+---n replay-completed {replay}?
| +--ro id subscription-id
+---n subscription-completed {configured}?
| +--ro id subscription-id
+---n subscription-modified
| +--ro id subscription-id
| +--ro (target)
| | +--:(stream)
| | | +--ro (stream-filter)?
| | | | +--:(by-reference)
| | | | | +--ro stream-filter-name stream-filter-ref
| | | | +--:(within-subscription)
| | | | +--ro (filter-spec)?
| | | | +--:(stream-subtree-filter)
| | | | | +--ro stream-subtree-filter? {subtree}?
| | | | +--:(stream-xpath-filter)
| | | | +--ro stream-xpath-filter? yang:xpath1.0 {xpath}?
| | | +--ro stream stream-ref
| | | +--ro replay-start-time? yang:date-and-time {replay}?
| | +--:(ypm:revision)
| | | +--ro ypm:revision rev:revision-date-or-label
| | +--:(ypm:revision-label)
| | +--ro ypm:revision-label? ysver:version
| +--ro stop-time? yang:date-and-time
| +--ro dscp? inet:dscp {dscp}?
| +--ro weighting? uint8 {qos}?
| +--ro dependency? subscription-id {qos}?
| +--ro transport? transport {configured}?
| +--ro encoding? encoding
| +--ro purpose? string {configured}?
+---n subscription-resumed
| +--ro id subscription-id
+---n subscription-started {configured}?
| +--ro id subscription-id
| +--ro (target)
| | +--:(stream)
| | | +--ro (stream-filter)?
| | | | +--:(by-reference)
| | | | | +--ro stream-filter-name stream-filter-ref
| | | | +--:(within-subscription)
| | | | +--ro (filter-spec)?
| | | | +--:(stream-subtree-filter)
| | | | | +--ro stream-subtree-filter? {subtree}?
| | | | +--:(stream-xpath-filter)
| | | | +--ro stream-xpath-filter? yang:xpath1.0 {xpath}?
| | | +--ro stream stream-ref
| | | +--ro replay-start-time? yang:date-and-time {replay}?
| | | +--ro replay-previous-event-time? yang:date-and-time {replay}?
| | +--:(ypm:revision)
| | | +--ro ypm:revision rev:revision-date-or-label
| | +--:(ypm:revision-label)
| | +--ro ypm:revision-label? ysver:version
| +--ro stop-time? yang:date-and-time
| +--ro dscp? inet:dscp {dscp}?
| +--ro weighting? uint8 {qos}?
| +--ro dependency? subscription-id {qos}?
| +--ro transport? transport {configured}?
| +--ro encoding? encoding
| +--ro purpose? string {configured}?
+---n subscription-suspended
| +--ro id subscription-id
| +--ro reason identityref
+---n subscription-terminated
+--ro id subscription-id
+--ro reason identityref
]]>The YANG module has two leaves augmenting the model of Subscription to YANG Notifications. file "ietf-yang-push-revision@2023-01-12.yang"
module ietf-yang-revisions {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-revisions";
prefix rev;
organization
"IETF NETMOD (Network Modeling) Working Group";
contact
"WG Web:
WG List:
Author: Joe Clarke
Author: Reshad Rahman
Author: Robert Wilton
Author: Balazs Lengyel
Author: Jason Sterne
";
description
"This YANG 1.1 module contains definitions and extensions to
support updated YANG revision handling.
Copyright (c) 2002 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 Revised 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 XXXX; see
the RFC itself for full legal notices.
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.";
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
// RFC Ed.: replace XXXX (inc above) with actual RFC number and
// remove this note.
revision 2022-11-29 {
rev:label "1.0.0-draft-ietf-netmod-yang-module-versioning-08";
description
"Initial version.";
reference
"XXXX: Updated YANG Module Revision Handling";
}
typedef revision-date {
type string {
pattern '[0-9]{4}-(1[0-2]|0[1-9])-(0[1-9]|[1-2][0-9]|3[0-1])';
}
description
"A date associated with a YANG revision.
Matches dates formatted as YYYY-MM-DD.";
reference
"RFC 7950: The YANG 1.1 Data Modeling Language";
}
typedef revision-label {
type string {
length "1..255";
pattern '[a-zA-Z0-9,\-_.+]+';
pattern '[0-9]{4}-[0-9]{2}-[0-9]{2}' {
modifier "invert-match";
error-message
"The revision-label must not match a revision-date.";
}
}
description
"A label associated with a YANG revision.
Alphanumeric characters, comma, hyphen, underscore, period
and plus are the only accepted characters. MUST NOT match
revision-date or pattern similar to a date.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label";
}
typedef revision-date-or-label {
type union {
type revision-date;
type revision-label;
}
description
"Represents either a YANG revision date or a revision label";
}
extension non-backwards-compatible {
description
"This statement is used to indicate YANG module revisions that
contain non-backwards-compatible changes.
The statement MUST only be a substatement of the 'revision'
statement. Zero or one 'non-backwards-compatible' statements
per parent statement is allowed. No substatements for this
extension have been standardized.
If a revision of a YANG module contains changes, relative to
the preceding revision in the revision history, that do not
conform to the backwards-compatible module update rules
defined in RFC-XXX, then the 'non-backwards-compatible'
statement MUST be added as a substatement to the revision
statement.
Conversely, if a revision does not contain a
'non-backwards-compatible' statement then all changes,
relative to the preceding revision in the revision history,
MUST be backwards-compatible.
A new module revision that only contains changes that are
backwards-compatible SHOULD NOT include the
'non-backwards-compatible' statement. An example of when an
author might add the 'non-backwards-compatible' statement is
if they believe a change could negatively impact clients even
though the backwards compatibility rules defined in RFC-XXXX
classify it as a backwards-compatible change.
Add, removing, or changing a 'non-backwards-compatible'
statement is a backwards-compatible version change.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.2,
non-backwards-compatible revision extension statement";
}
extension label {
argument revision-label;
description
"The revision label can be used to provide an additional
versioning identifier associated with a module or submodule
revision. One such scheme that could be used is [XXXX:
ietf-netmod-yang-semver].
The format of the revision label argument MUST conform to the
pattern defined for the revision label typedef in this module.
The statement MUST only be a substatement of the revision
statement. Zero or one revision label statements per parent
statement are allowed. No substatements for this extension
have been standardized.
Revision labels MUST be unique amongst all revisions of a
module or submodule.
Adding a revision label is a backwards-compatible version
change. Changing or removing an existing revision label in
the revision history is a non-backwards-compatible version
change, because it could impact any references to that
revision label.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.3, Revision label";
}
extension revision-label-scheme {
argument revision-label-scheme-base;
description
"The revision label scheme specifies which revision label
scheme the module or submodule uses.
The mandatory revision-label-scheme-base argument MUST be an
identity derived from revision-label-scheme-base.
This extension is only valid as a top-level statement, i.e.,
given as as a substatement to 'module' or 'submodule'. No
substatements for this extension have been standardized.
This extension MUST be used if there is a revision label
statement in the module or submodule.
Adding a revision label scheme is a backwards-compatible
version change. Changing a revision label scheme is a
non-backwards-compatible version change, unless the new
revision label scheme is backwards-compatible with the
replaced revision label scheme. Removing a revision label
scheme is a non-backwards-compatible version change.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.3.1, Revision label scheme extension statement";
}
extension recommended-min {
argument revision-date-or-label;
description
"Recommends the revision of the module that may be imported to
one that matches or is derived from the specified
revision-date or revision label.
The argument value MUST conform to the
'revision-date-or-label' defined type.
The statement MUST only be a substatement of the import
statement. Zero, one or more 'recommended-min' statements per
parent statement are allowed. No substatements for this
extension have been standardized.
If specified multiple times, then any module revision that
satisfies at least one of the 'recommended-min' statements is
an acceptable recommended revision for import.
A particular revision of an imported module adheres to an
import's 'recommended-min' extension statement if the imported
module's revision history contains a revision statement with a
matching revision date or revision label.
Adding, removing or updating a 'recommended-min' statement to
an import is a backwards-compatible change.";
reference
"XXXX: Updated YANG Module Revision Handling; Section 4,
Recommending a minimum revision for module imports";
}
identity revision-label-scheme-base {
description
"Base identity from which all revision label schemes are
derived.";
reference
"XXXX: Updated YANG Module Revision Handling;
Section 3.3.1, Revision label scheme extension statement";
}
}
]]>The security considerations for the YANG notifications subscription
mechanism are described in . This documents adds
no additional security considerations.This document has no IANA actions.The authors would like to thank xxx for their review and valuable
comments.Extensible Markup Language (XML) 1.0 (Fifth Edition)World Wide Web Consortium Recommendation
REC-xml-20081126