draft-tgraf-netconf-yang-notifications-versioning-00.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="2"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std"
     docName="draft-tgraf-netconf-yang-notifications-versioning-00"
     ipr="trust200902">
  <front>
    <title abbrev="YANG Notifications Versioning">Support of Versioning in
    YANG Notifications Subscription</title>

    <author fullname="Thomas Graf" initials="T" surname="Graf">
      <organization>Swisscom</organization>

      <address>
        <postal>
          <street>Binzring 17</street>

          <city>Zurich</city>

          <code>8045</code>

          <country>Switzerland</country>
        </postal>

        <email>thomas.graf@swisscom.com</email>
      </address>
    </author>

    <author fullname="Benoit Claise" initials="B" surname="Claise">
      <organization>Huawei</organization>

      <address>
        <email>benoit.claise@huawei.com</email>
      </address>
    </author>

    <author fullname="Alex Huang Feng" initials="A." surname="Huang Feng">
      <organization>INSA-Lyon</organization>

      <address>
        <postal>
          <street/>

          <city>Lyon</city>

          <region/>

          <code/>

          <country>France</country>
        </postal>

        <phone/>

        <facsimile/>

        <email>alex.huang-feng@insa-lyon.fr</email>

        <uri/>
      </address>
    </author>

    <date day="20" month="October" year="2022"/>

    <abstract>
      <t>This document extends the YANG notifications subscription mechanism
      to specify the YANG module semantic version at the subscription. Then, a
      new extension with new metadata of the YANG push update notification
      header is proposed.</t>
    </abstract>

    <note title="Requirements Language">
      <t>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
      <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when,
      they appear in all capitals, as shown here.</t>
    </note>
  </front>

  <middle>
    <section anchor="Introduction" title="Introduction">
      <t>In order to process the received YANG push notification messages
      described in section 3.7 of <xref target="RFC8641"/> 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.</t>

      <t>This specification applies to the YANG push configured subscriptions
      defined in Section 2.5 of <xref target="RFC8639"/>, where a publisher is
      configured to stream notification out of band, as opposed to dynamic
      subscriptions defined in Section 2.4 of <xref target="RFC8641"/>, 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.</t>

      <t>This semantic reference is available during the subscription period
      described in Section 3.6 of <xref target="RFC8641"/> where for each
      subscription a locally unique subscription ID described in Section 4.3.2
      of <xref target="RFC8641"/> is being issued and streamed as metadata
      with the notification message in the YANG push message header. This
      implies that the YANG receiver needs to lookup the subscription
      inventory for a subscription ID in each notification message to
      determine the YANG module name, namespace, and filter definitions.</t>

      <t>The semantics can change between different YANG module revisions. The
      YANG module version statement is specified in Section 7.1.2 of <xref
      target="RFC6020"/> and states that the newer revision needs to be
      backward compatible to the previous revision. Section 3.1 of <xref
      target="I-D.ietf-netmod-yang-module-versioning"/> specifies that newer
      semantic versions introduced in <xref
      target="I-D.ietf-netmod-yang-semver"/> MAY not be backward compatible to
      the previous version when indicated with non-backwards-compatible
      keyword.</t>

      <t>The YANG notifications subscription mechanism defined in <xref
      target="RFC8641"/> 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.</t>

      <t>This documents extends the current YANG notifications subscription
      mechanism to allow to subscribe to a specific revision or latest
      semantic version to which the YANG module version needs to be backward
      compatible to and advertises its specific YANG module revision inband.
      Besides the existing Subscription ID, the YANG module name, namespace,
      revision and filtering metadata is added to the YANG push notification
      header to lift the YANG push receiver need to lookup the subscription
      inventory information.</t>
    </section>

    <section anchor="Datastore-Selection"
             title="Extend the Datastore Selection">
      <t>The YANG notifications subscription OPTIONALLY can be restricted to
      the following YANG module revision for future capabilities:</t>

      <dl>
        <dt>latest:</dt>

        <dd>Restricts the subscription to the latest YANG module
        revision.</dd>
      </dl>

      <dl>
        <dt>revision:</dt>

        <dd>Restricts the subscription to a specific YANG module revision.
        Example 2014-05-08.</dd>
      </dl>

      <dl>
        <dt>latest-compatible-semversion:</dt>

        <dd>Restricts the subscription to the latest compatible YANG module
        semantic version referenced to. Example 2.0.0.</dd>
      </dl>

      <t>If nothing is specified, latest YANG module version is implied.</t>
    </section>

    <section anchor="Streaming-Update"
             title="Extend the Metadata in Streaming Update">
      <t>Along with the subscribed content, besides the Subcription ID, the
      following metadata objects are part of a "push-update" or
      "push-change-update" notification.</t>

      <dl>
        <dt>module:</dt>

        <dd>Describes the YANG module name for the related streamed
        content.</dd>
      </dl>

      <dl>
        <dt>namespace:</dt>

        <dd>Describes the YANG module namespace as specified in Section 7.1.3
        of <xref target="RFC6020"/> for the related streamed content.</dd>
      </dl>

      <dl>
        <dt>revision:</dt>

        <dd>Describes the YANG module revision as specified in Section 7.1.2
        of <xref target="RFC6020"/> for the related streamed content.</dd>
      </dl>

      <dl>
        <dt>revision-label:</dt>

        <dd>Describes the YANG module semantic version as specified in <xref
        target="I-D.ietf-netmod-yang-semver"/> for the related streamed
        content.</dd>
      </dl>

      <dl>
        <dt>datastore-xpath-filter:</dt>

        <dd>Describes the YANG module xpath filter as specified in Section 6.4
        of <xref target="RFC6020"/> for the related streamed content.</dd>
      </dl>

      <dl>
        <dt>datastore-subtree-filter:</dt>

        <dd>Describes the YANG module subtree filter as specified in Section 6
        of <xref target="RFC6241"/> for the related streamed content.</dd>
      </dl>

      <t>Figure 1 provides an example of a notification message with the YANG
      module name, revision, revision label and datastore-xpath-filter for a
      subscription tracking the operational status of a single Ethernet
      interface (per <xref target="RFC8343"/>). This notification message is
      encoded XML <xref target="W3C.REC-xml-20081126"/> over the Network
      Configuration Protocol (NETCONF) as per <xref target="RFC8640"/>.</t>

      <figure>
        <artwork><![CDATA[

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 <eventTime>2022-09-02T10:59:55.32Z</eventTime>
 <push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
   <id>101</id>
   <module>ietf-interfaces</module>
   <namespace>urn:ietf:params:xml:ns:yang:ietf-interfaces</namespace>
   <revision>2014-05-08</revision>
   <revision-label>1.0.0</revision-label>
   <datastore-xpath-filter>ietf-interfaces:interfaces</datastore-xpath-filter>
   <datastore-contents>
      <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
       <interface>
         <name>eth0</name>
         <oper-status>up</oper-status>
       </interface>
     </interfaces>
   </datastore-contents>
 </push-update>
</notification>

 Figure 1: XML Push Example for a Periodical Notification Message

        ]]></artwork>
      </figure>

      <t>Figure 2 provides an example of a JSON encoded, <xref
      target="RFC8259"/>, notification message over HTTPS-based <xref
      target="I-D.ietf-netconf-https-notif"/> or UDP-based <xref
      target="I-D.ietf-netconf-udp-notif"/> transport for the same
      subscription.</t>

      <figure>
        <artwork><![CDATA[

{
    "ietf-notification:notification": {
        "eventTime": "2022-09-02T10:59:55.32Z",
        "ietf-yang-push:push-update": {
            "id": 101,{
            "module": "ietf-interfaces",{
            "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces",{
            "revision": "2014-05-08",{
            "revision-label": "1.0.0",{
            "datastore-xpath-filter": "ietf-interfaces:interfaces",
            "datastore-contents": {
                "ietf-interfaces:interface": {
                    "name": {
                        "eth0": {
                                "oper-status": "up",
                                }
                             }
                          }
                       }
                    }
                 }
              }
           }
       }
   }
}

 Figure 2: JSON Push Example for a Periodical Notification Message

        ]]></artwork>
      </figure>
    </section>

    <section anchor="YANG-push-metadata-module"
             title="The &quot;ietf-yang-push-metadata&quot; Module">
      <section anchor="YANG-metadata-model" title="Data Model Overview">
        <t>This YANG module augments the "ietf-yang-push" module to add
        subcription metadata into the "push-update" and "push-change-update"
        notification and the ability to define the "revision" and
        "revision-label" in the "establish-subscription" and
        "modify-subscription" in the datastore push subscription.</t>

        <t><figure>
            <artwork><![CDATA[
module: ietf-yang-push-metadata

  augment /yp:push-update:
    +--ro module?                     string
    +--ro namespace?                  string
    +--ro revision?                   rev:revision-date-or-label
    +--ro revision-label?             ysver:version
    +--ro datastore-xpath-filter?     yang:xpath1.0 {sn:xpath}?
    +--ro datastore-subtree-filter?   <anydata> {sn:subtree}?
  augment /yp:push-change-update:
    +--ro module?                     string
    +--ro namespace?                  string
    +--ro revision?                   rev:revision-date-or-label
    +--ro revision-label?             ysver:version
    +--ro datastore-xpath-filter?     yang:xpath1.0 {sn:xpath}?
    +--ro datastore-subtree-filter?   <anydata> {sn:subtree}?
  augment /sn:establish-subscription/sn:input/sn:target:
    +-- revision?         rev:revision-date-or-label
    +-- revision-label?   ysver:version
  augment /sn:modify-subscription/sn:input/sn:target:
    +-- revision?         rev:revision-date-or-label
    +-- revision-label?   ysver:version
  augment /sn:subscription-started/sn:target:
    +-- revision?         rev:revision-date-or-label
    +-- revision-label?   ysver:version
  augment /sn:subscription-modified/sn:target:
    +-- revision?         rev:revision-date-or-label
    +-- revision-label?   ysver:version
  augment /sn:subscriptions/sn:subscription/sn:target:
    +--rw revision?         rev:revision-date-or-label
    +--rw revision-label?   ysver:version
]]></artwork>
          </figure></t>
      </section>

      <section anchor="YANG-metadata-module" title="YANG Module">
        <t>The YANG module has six leaves augmenting the model of <xref
        target="RFC8641">YANG-push</xref>.</t>

        <t><figure>
            <artwork><![CDATA[
<CODE BEGINS> file "ietf-yang-push-metadata@2022-10-10.yang"
module ietf-yang-push-metadata {
  yang-version 1.1;
  namespace
    "urn:ietf:params:xml:ns:yang:ietf-yang-push-metadata";
  prefix ypm;
  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-yang-push {
    prefix yp;
    reference
      "RFC 8641: Subscription to YANG Notifications for Datastore Updates";
  }
  import ietf-yang-revisions {
    prefix rev;
    reference
      "RFC XXXX: draft-ietf-netmod-yang-module-versioning-06, Updated YANG
      Module Revision Handling";
  }
  import ietf-yang-semver {
    prefix ysver;
    reference
      "RFC XXXX: draft-ietf-netmod-yang-semver-07, YANG Semantic Versioning";
  }

  organization "IETF NETCONF (Network Configuration) Working Group";
  contact
    "WG Web:   <http:/tools.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>

     Authors:  Thomas Graf
               <mailto:thomas.graf@swisscom.com>
               Benoit Claise
               <mailto:benoit.claise@huawei.com>
               Alex Huang Feng
               <mailto:alex.huang-feng@insa-lyon.fr>";

  description
    "Defines YANG push event notification header with metadata.

    Copyright (c) 2022 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.";

  revision 2022-09-21 {
    description
      "First revision";
    reference
      "RFC XXXX: Support of Versioning in YANG Notifications Subscription";
  }

  feature yang-push-metadata-supported {
    description
      "This feature indicates the YANG Notifications have the metadata 
      defined in this YANG module.";
  }

  grouping yang-push-module-version {
    leaf revision {
      type rev:revision-date-or-label;
      description
        "This references the YANG module revision of the sent notification.";
    }
    leaf revision-label {
      type ysver:version;
      description
        "This references the YANG module semversion of the sent notification.";
    }
  }

  grouping yang-push-metadata {
    leaf module {
      type string;
      description
        "This references the YANG module of the sent notification.";
    }
    leaf namespace {
      type string;
      description
        "This references the YANG module namespace of the sent notification.";
    }

    uses ypm:yang-push-module-version;

    leaf datastore-xpath-filter {
      type yang:xpath1.0;
      if-feature "sn:xpath";
      description
        "This references the YANG module xpath of the sent notification.";
    }
    anydata datastore-subtree-filter {
      if-feature "sn:subtree";
      description
        "This references the YANG module subtree of the sent notification.";
    }
  }
  // Event notifications
  augment "/yp:push-update" {
    description
      "This augmentation adds the module, the namespace, the revision, the 
      semversion, the xpath and the subtree in the push-update notification";
    uses ypm:yang-push-metadata;
  }

  augment "/yp:push-change-update" {
    description
      "This augmentation adds the module, the namespace, the revision, the 
      semversion, the xpath and the subtree in the push-change-update notification";
      uses ypm:yang-push-metadata;
  }

  // Subscription parameters
  augment "/sn:establish-subscription/sn:input/sn:target" {
    uses ypm:yang-push-module-version;
  }
  augment "/sn:modify-subscription/sn:input/sn:target" {
    uses ypm:yang-push-module-version;
  }

  // Subscription notifications
  augment "/sn:subscription-started/sn:target" {
    uses ypm:yang-push-module-version;
  }
  augment "/sn:subscription-modified/sn:target" {
    uses ypm:yang-push-module-version;
  }

  // Subscription container
  augment "/sn:subscriptions/sn:subscription/sn:target" {
    uses ypm:yang-push-module-version;
  }
}
<CODE ENDS>]]></artwork>
          </figure></t>
      </section>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>The security considerations for the YANG notifications subscription
      mechanism are described in <xref target="RFC8641"/>. This documents adds
      no additional security considerations.</t>
    </section>

    <section anchor="IANA_Considerations" title="IANA Considerations">
      <t>This document has no IANA actions.</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>The authors would like to thank xxx for their review and valuable
      comments.</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include='reference.RFC.2119'?>

      <?rfc include='reference.RFC.6020'?>

      <?rfc include='reference.RFC.6241'?>

      <?rfc include='reference.RFC.8174'?>

      <?rfc include='reference.RFC.8639'?>

      <?rfc include='reference.RFC.8641'?>

      <?rfc include='reference.I-D.ietf-netmod-yang-module-versioning'?>

      <?rfc include='reference.I-D.ietf-netmod-yang-semver'?>
    </references>

    <references title="Informative References">
      <?rfc include='reference.RFC.8259'?>

      <?rfc include='reference.RFC.8343'?>

      <?rfc include='reference.RFC.8640'?>

      <?rfc include='reference.I-D.ietf-netconf-https-notif'?>

      <?rfc include='reference.I-D.ietf-netconf-udp-notif'?>

      <reference anchor="W3C.REC-xml-20081126"
                 derivedAnchor="W3C.REC-xml-20081126" quoteTitle="true"
                 target="https://www.w3.org/TR/2008/REC-xml-20081126">
        <front>
          <title>Extensible Markup Language (XML) 1.0 (Fifth Edition)</title>

          <author fullname="Tim Bray" initials="T." surname="Bray">
            <organization showOnFrontPage="true"/>
          </author>

          <author fullname="Jean Paoli" initials="J." surname="Paoli">
            <organization showOnFrontPage="true"/>
          </author>

          <author fullname="Michael Sperberg-McQueen" initials="M."
                  surname="Sperberg-McQueen">
            <organization showOnFrontPage="true"/>
          </author>

          <author fullname="Eve Maler" initials="E." surname="Maler">
            <organization showOnFrontPage="true"/>
          </author>

          <author fullname="Francois Yergeau" initials="F." surname="Yergeau">
            <organization showOnFrontPage="true"/>
          </author>

          <date month="November" year="2008"/>
        </front>

        <refcontent>World Wide Web Consortium Recommendation
        REC-xml-20081126</refcontent>
      </reference>
    </references>
  </back>
</rfc>