YANG-Push Operational Data Observability Enhancements

2.1. Complexities in Modelling the Operational State Datastore

The YANG abstraction of a single datastore of related consistent data works very well for configuration that has a strong requirement to be self consistent, and that is always updated, and validated, in a transactional way. But for producers of telemetry data, the YANG abstraction of a single operational datastore is not really possible for devices managing a non-trivial quantity of operational data.¶

Some systems may store their operational data in a single logical database, yet it is less likely that the operational data can always be updated in a transactional way, and often for memory efficiency reasons such a database does not store individual leaves, but instead semi-consistent records of data at a container or list entry level.¶

For other systems, the operational information may be distributed across multiple internal nodes (e.g., linecards), and potentially many different process daemons within those distributed nodes. Such systems generally cannot exhibit full consistency [Consistency] of the operational data (which would require transactional semantics across all daemons and internal nodes), only offering an eventually consistent [Eventual_Consistency] view of the data instead.¶

In practice, many network devices will manage their operational data as a combination of some data being stored in a central operational datastore, and other, higher scale, and potentially more frequently changing data (e.g., statistics or FIB information) being stored elsewhere in a more memory efficient and performant way.¶

3.1. New encoding format

This document proposes a new opt-in YANG-Push encoding format to use instead of the "push-update" and "push-change-update" notifications defined in [RFC8641].¶

There are a few reasons for specifying a new encoding format:¶

1. To use the same encoding format for both periodic and on-change messages, allowing the same messages to be easily received and stored in a time-series database, making use of the same message schema when traversing message buses, such as Apache Kafka.¶

2. To allow the schema of the notifications to be rooted to the subscription point rather than always being to the root of the operational datastore schema. This allows messages to be slightly less indented, and makes it easier to convert from a YANG schema to an equivalent message bus schema, where each message is defined with its own schema, rather than a single datastore schema.¶

3. To move away from the somewhat verbose YANG Patch format [RFC8072], that is not really a great fit for encoding changes of operational data. Many systems cannot necessarily distinguish between create versus update events (particularly for new subscriptions or after recovering from internal failures within the system), and hence cannot faithfully implement the full YANG Patch semantics defined in [RFC8641].¶

4. To allow the device to split a subscription into smaller child subscriptions for more efficient independent and concurrent processing. I.e., reusing the ideas from [I-D.ietf-netconf-distributed-notif]. However, all child subscriptions are still encoded from the same subscription point.¶

The practical differences in the encodings may be better illustrated via the examples in Appendix B.¶

3.2. Combined periodic and on-change subscription

Sometimes it is helpful to have a single subscription that covers both periodic and on-change notifications (perhaps with dampening).¶

There are two ways in which this may be useful:¶

1. For generally slow changing data (e.g., a device's physical inventory), then on-change notifications may be most appropriate. However, in case there is any lost notification that isn't always detected, for any reason, then it may also be helpful to have a slow cadence periodic backup notification of the data (e.g., once every 24 hours), to ensure that the management systems would should always eventually converge on the current state in the network.¶

2. For data that is generally polled on a periodic basis (e.g., once every 10 minutes) and put into a time series database, then it may be helpful for some data trees to also get more immediate notifications that the data has changed. Hence, a combined periodic and on-change subscription, potentially with some dampening, would facilitate more frequent notifications of changes of the state, to reduce the need of having to always wait for the next periodic event.¶

Hence, this document introduces the fairly intuitive "periodic-and-on-change" update trigger that creates a combined periodic and on-change subscription, and allows the same parameters to be configured. For some use cases, e.g., where a time-series database is being updated, the new encoding format proposed previously may be most useful.¶

3.3. Open Issues & Other Potential Enhancements/Changes

This section lists some other potential issues and enhancements that should be considered as part of this work. If there is working group interest in progressing this work, then the issues in this section could potentially be better managed as github issues.¶

1. Should we consider a version of the JSON encoding that excludes module prefixes (either everywhere, or perhaps only include the top module prefix). The reasoning for considering this is to potentially better align the JSON data with how the schema data may be modeled in other data systems, e.g., Kafka. Obviously, this requires that there be no duplicate data node names in different module namespaces, but most sane device schemas would avoid this anyway.¶

2. Do we make use of the new notification-envelope format [I-D.netana-netconf-notif-envelope] as the mandatory and only required notification format for these new forms of subscriptions. I.e., reducing complexity by removing unnecessary flexibility and options?¶

3. Document how sub-subscriptions can be used to split a higher level subscription into multiple smaller more efficient subscriptions for the device (that can be handled concurrently).¶

4. The document's current focus is on configured subscriptions, aligned to the proposed initial deployment requirements, but the solution should probably be extended to support dynamic subscriptions, presuming that it is not hard to do so.¶

5. Some of the YANG-Push behavior is more complex and expensive to implement (e.g., the SHOULD requirement to suggest suitable alternative subscription parameters if a subscription is rejected, subscription dependencies). Should this document update RFC 8639 or RFC 8641 to indicate that those requirements do not apply to these new extended subscriptions? The goal of this work should be to specify the minimal required functionality to meet the requirements.¶

6. What document format should this work take? The currently proposed approach is to add extra extensions to YANG-Push to cover the required functionality. An alternative approach could be to write a RFC 8641-bis, or a 'YANG-Push lite'.¶

7. Currently the encoding and transport parameters are per subscription, but it may make more sense for these to be per receiver definition. I.e., if you want to use different transports and encodings to the same receiver this should still be possible, but would require a second receiver to be defined with the same destination IP address, but a different name. Currently, the newly proposed encoding format is configured per subscription (mirroring equivalent transport and encoding configuration), but alternatively it could be configured per receiver.¶

8. We should consider how a subscription could support multiple subscription paths. The potential tricky aspect of this to consider the subscription bind point. Related to this is whether XPath 1.0 is the best way of specifying these bind points, or whether it should something closer to the NACM node-instance-identifier [RFC6536], but perhaps using something closer to the JSON style encoding of instance identifier [RFC7951], section 6.11; or JSON PATH [RFC9535].¶

9. What level of subscription filtering do we need and want to support? For example, I doubt that anyone allows for full XPath filtering of operational data subscriptions because they are likely to be very computationally expensive to implement. Is there an easier way of expressing the filter requirements rather than using subtree filtering. Note, this could be added in a future release.¶

3.4. YANG Extensions Data Model

This sections shows the raw YANG tree output just for the ietf-yp-ext.yang module, and the proposed YANG module.¶

module: ietf-yp-ext

  augment /sn:subscription-started/yp:update-trigger:
    +--:(periodic-and-on-change) {yp:on-change}?
       +-- periodic-and-on-change!
          +-- period              yp:centiseconds
          +-- anchor-time?        yang:date-and-time
          +-- dampening-period?   yp:centiseconds
          +-- sync-on-start?      boolean
          +-- excluded-change*    yp:change-type
  augment /sn:subscription-started:
    +--ro common-notification-format?   boolean
  augment /sn:subscription-modified/yp:update-trigger:
    +--:(periodic-and-on-change) {yp:on-change}?
       +-- periodic-and-on-change!
          +-- period              yp:centiseconds
          +-- anchor-time?        yang:date-and-time
          +-- dampening-period?   yp:centiseconds
          +-- sync-on-start?      boolean
          +-- excluded-change*    yp:change-type
  augment /sn:subscription-modified:
    +--ro common-notification-format?   boolean
  augment /sn:subscriptions/sn:subscription/yp:update-trigger:
    +--:(periodic-and-on-change) {yp:on-change}?
       +--rw periodic-and-on-change!
          +--rw period              yp:centiseconds
          +--rw anchor-time?        yang:date-and-time
          +--rw dampening-period?   yp:centiseconds
          +--rw sync-on-start?      boolean
          +--rw excluded-change*    yp:change-type
  augment /sn:subscriptions/sn:subscription:
    +--rw common-notification-format?   boolean

  notifications:
    +---n update
       +--ro id?                   sn:subscription-id
       +--ro subscription-path?    yang:xpath1.0
       +--ro target-path?          string
       +--ro snapshot-type?        enumeration
       +--ro observation-time?     yang:date-and-time
       +--ro datastore-snapshot?   <anydata>
       +--ro incomplete?           empty

<CODE BEGINS> file "ietf-yp-ext@2024-10-18.yang"

module ietf-yp-ext {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-yp-ext";
  prefix yp-ext;

  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 Datastores";
  }

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

     Author:  Robert Wilton
              <mailto:rwilton@cisco.com>";

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

     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) 2024 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 2024-10-18 {
    description
      "Initial revision.";
    reference
      "XXX: YANG Push Observability Extensions ";
  }

  /*
   * FEATURES
   */

  /*
   * IDENTITIES
   */

  /*
   * TYPE DEFINITIONS
   */

  /*
   * GROUP DEFINITIONS
   */

  grouping periodic-and-on-change {
    description
      "This grouping describes the datastore-specific subscription
       that represents a combined periodic and on-change subscription.";
    container periodic-and-on-change {
      presence
        "A combined periodic and on-change subscription";
      description
        "The publish notifies the receiver on the specific
          periodic, and also whenever any of the data changes.";
      leaf period {
        type yp:centiseconds;
        mandatory true;
        description
          "Duration of time that should occur between periodic
          push updates, in units of 0.01 seconds.";
      }
      leaf anchor-time {
        type yang:date-and-time;
        description
          "Designates a timestamp before or after which a series
          of periodic push updates are determined.  The next
          update will take place at a point in time that is a
          multiple of a period from the 'anchor-time'.
          For example, for an 'anchor-time' that is set for the
          top of a particular minute and a period interval of a
          minute, updates will be sent at the top of every
          minute that this subscription is active.";
      }
      leaf dampening-period {
        type yp:centiseconds;
        default "0";
        description
          "Specifies the minimum interval between the assembly of
            successive update records for a single receiver of a
            subscription.  Whenever subscribed objects change and
            a dampening-period interval (which may be zero) has
            elapsed since the previous update record creation for
            a receiver, any subscribed objects and properties
            that have changed since the previous update record
            will have their current values marshalled and placed
            in a new update record.";
      }
      leaf sync-on-start {
        type boolean;
        default "true";
        description
          "When this object is set to 'false', (1) it restricts an
          on-change subscription from sending 'push-update'
          notifications and (2) pushing a full selection per the
          terms of the selection filter MUST NOT be done for
          this subscription.  Only updates about changes
          (i.e., only 'push-change-update' notifications)
          are sent.  When set to 'true' (the default behavior),
          in order to facilitate a receiver's synchronization,
          a full update is sent, via a 'push-update' notification,
          when the subscription starts.  After that,
          'push-change-update' notifications are exclusively sent,
          unless the publisher chooses to resync the subscription
          via a new 'push-update' notification.";
      }
      leaf-list excluded-change {
        type yp:change-type;
        description
          "Used to restrict which changes trigger an update.  For
           example, if a 'replace' operation is excluded, only the
           creation and deletion of objects are reported.

           TODO - Do we want this leaf?";
      }
    }
  }

  grouping common-notification-format {
    description
      "This grouping describes the common-notif-format leaf that
       controls whether the new common message format is used for periodic
       and on-change notifications.";
    leaf common-notification-format {
      type boolean;
      default "false";
      description
        "This leaf controls whether the new common message format
         is used for periodic and on-change notifications.  If set
         to 'true', the new common message format is used.  If set
         to 'false', the old message format is used.

         TODO - Should we support hierarchical configuration here
         (e.g., also add the leaf to the subscription container,
         or it could be added to the receiver instead)?";
    }
  }

  /*
   * RPCs
   */

  /*
   * NOTIFICATIONS
   */

  notification 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.";
    }

    leaf subscription-path {
      type yang:xpath1.0;
      description
        "The subscription path indicates the schema path from the root of the
         schema tree to the node, for which the updated state is being
         notified, or a notification that is has been deleted.

         TODO - Make this an instance data ref";
    }

    leaf target-path {
      type string;
    }

    leaf snapshot-type {
      type enumeration {
        enum "periodic" {
          description
            "The update message is due to a periodic update.";
        }
        enum "on-change-update" {
          description
            "The update message is due to an on-change update.  This
             means that one or more fields have changed under the
             snapshot path.

             TODO - Split this into a on-change-delete msg?";
        }
        enum "on-change-delete" {
          description
            "The update message is due to an on-change event where
             the data node at the target path has been delete.";
        }
        enum "resync" {
          description
            "This indicates that the update is to resynchronize the
             state, e.g., after a subscription started notification.

             Ideally, the resync message SHOULD be the first
             notification sent when a subscription has started, but
             it is not gauranteed or required to be the first
             (e.g., if an on-change event occurs).

             These messages can be used to ensure that all state
             has been sent to the client, and can be used to purge
             stale data.

             TODO - In the distributed notification case, need a
             notification to indicate that all child subscriptions
             have been sent.";
        }
      }
      description
        "This indicates the type of notification message that is being sent.";
    }

    // Could add observation time here.
    leaf observation-time {
      type yang:date-and-time;
      description
        "The time that the update was observed by the publisher.";
    }

    anydata datastore-snapshot {
      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.

        Used for snapshot types except for 'on-change-delete'.";
    }

    leaf incomplete {
      type empty;
      description
        "This is a flag that indicates that not all datastore
        nodes subscribed to are included with this update.  Receivers
        of this data SHOULD NOT assume that any missing data has been
        implicitly deleted.

        TODO - Do we still want this flag, or would it be
        better to notify this event out of band?";
    }
  }

  augment "/sn:subscription-started/yp:update-trigger" {
    if-feature "yp:on-change";
    description
      "Allow a subscription started notification to signal a
       combined periodic and on-change subscription.";
    case periodic-and-on-change {
      uses periodic-and-on-change;
    }
  }

  augment "/sn:subscription-started" {
    description
      "Allow a subscription started notification to signal that it
       uses the common notification format.";
    uses common-notification-format;
  }

  augment "/sn:subscription-modified/yp:update-trigger" {
    if-feature "yp:on-change";
    description
      "Allow a subscription started notification to signal a
       combined periodic and on-change subscription.";
    case periodic-and-on-change {
      uses periodic-and-on-change;
    }
  }

  augment "/sn:subscription-modified" {
    description
      "Allow a subscription modified notification to signal that it
       uses the common notification format.";
    uses common-notification-format;
  }

  /*
   * DATA NODES
   */

  augment "/sn:subscriptions/sn:subscription/yp:update-trigger" {
    when 'yp:datastore';
    if-feature "yp:on-change";
    description
      "This augmentation adds objects to a subscription that are
       specific to a datastore subscription, i.e., a subscription to
       a stream of datastore node updates.";
    case periodic-and-on-change {
      uses periodic-and-on-change;
    }
  }

  augment "/sn:subscriptions/sn:subscription" {
    uses common-notification-format;
  }
}

<CODE ENDS>

Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC5277]

Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, <https://www.rfc-editor.org/rfc/rfc5277>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8641]

Clemm, A. and E. Voit, "Subscription to YANG Notifications for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, September 2019, <https://www.rfc-editor.org/rfc/rfc8641>.

Informative References

[Consistency]

Wikipedia, "Consistency (database systems)", <https://en.wikipedia.org/wiki/Consistency_(database_systems)>.

[Eventual_Consistency]

Rouse, M., "Eventual Consistency", <https://www.techopedia.com/definition/29165/eventual-consistency>.

[I-D.ietf-netconf-distributed-notif]

Zhou, T., Zheng, G., Voit, E., Graf, T., and P. Francois, "Subscription to Distributed Notifications", Work in Progress, Internet-Draft, draft-ietf-netconf-distributed-notif-10, 18 October 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-netconf-distributed-notif-10>.

[I-D.ietf-nmop-network-anomaly-architecture]

Graf, T., Du, W., and P. Francois, "An Architecture for a Network Anomaly Detection Framework", Work in Progress, Internet-Draft, draft-ietf-nmop-network-anomaly-architecture-01, 20 October 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-nmop-network-anomaly-architecture-01>.

[I-D.ietf-nmop-yang-message-broker-integration]

Graf, T. and A. Elhassany, "An Architecture for YANG-Push to Message Broker Integration", Work in Progress, Internet-Draft, draft-ietf-nmop-yang-message-broker-integration-05, 19 October 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-nmop-yang-message-broker-integration-05>.

[I-D.netana-netconf-notif-envelope]

Feng, A. H., Francois, P., Graf, T., and B. Claise, "Extensible YANG model for YANG-Push Notifications", Work in Progress, Internet-Draft, draft-netana-netconf-notif-envelope-00, 18 October 2024, <https://datatracker.ietf.org/doc/html/draft-netana-netconf-notif-envelope-00>.

[I-D.tgraf-netconf-notif-sequencing]

Graf, T., Quilbeuf, J., and A. H. Feng, "Support of Hostname and Sequencing in YANG Notifications", Work in Progress, Internet-Draft, draft-tgraf-netconf-notif-sequencing-06, 29 June 2024, <https://datatracker.ietf.org/doc/html/draft-tgraf-netconf-notif-sequencing-06>.

[I-D.tgraf-netconf-yang-push-observation-time]

Graf, T., Claise, B., and A. H. Feng, "Support of Observation Timestamp in YANG-Push Notifications", Work in Progress, Internet-Draft, draft-tgraf-netconf-yang-push-observation-time-02, 3 July 2024, <https://datatracker.ietf.org/doc/html/draft-tgraf-netconf-yang-push-observation-time-02>.

[Kafka]

Apache.org, "Apache Kafka", <https://kafka.apache.org/>.

[RFC6536]

Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012, <https://www.rfc-editor.org/rfc/rfc6536>.

[RFC7951]

Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/rfc/rfc7951>.

[RFC8072]

Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2017, <https://www.rfc-editor.org/rfc/rfc8072>.

[RFC9535]

Gössner, S., Ed., Normington, G., Ed., and C. Bormann, Ed., "JSONPath: Query Expressions for JSON", RFC 9535, DOI 10.17487/RFC9535, February 2024, <https://www.rfc-editor.org/rfc/rfc9535>.

B.1. Example of an [RFC8641] style push-update notification

This example illustrates a periodic update message for a subscription at "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces" that is returning data from two internal data providers, one of which is returning data for "interface-summary" and the other that is returning data for "interfaces". The device resident management agents stitches the reply together from the two data providers into a single data tree before returning it in a single message.¶

For the periodic message to be correct, and to allow it to replace any previous periodic message published on that subscription, it must include all data below the subscription path. This may increase the total amount of internal IPC within the device and make the timestamps less accurate, since the observation timestamp only reports when the device starts polling the data providers. If those providers are distributed across multiple processes and linecards then it may take a bit of time to complete the periodic on-change.¶

{
  "ietf-notification:notification": {
    "eventTime": "2024-09-27T14:16:27.773Z",
    "ietf-yang-push:push-update": {
      "id": 1,
      "ietf-yp-observation:timestamp": "2024-09-27T14:16:27.773Z",
      "ietf-yp-observation:point-in-time": "current-accounting",
      "datastore-contents": {
        "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces": {
          "interface-summary": {
            "interface-type": [
              {
                "interface-type-name": "IFT_GETHERNET",
                "interface-type-description": "GigabitEthernet",
                "interface-counts": {
                  "interface-count": 5,
                  "up-interface-count": 2,
                  "down-interface-count": 0,
                  "admin-down-interface-count": 3
                }
              }
            ],
            "interface-counts": {
              "interface-count": 8,
              "up-interface-count": 5,
              "down-interface-count": 0,
              "admin-down-interface-count": 3
            }
          },
          "interfaces": {
            "interface": [
              {
                "interface-name": "GigabitEthernet0/0/0/0",
                "interface": "GigabitEthernet0/0/0/0",
                "state": "im-state-admin-down",
                "line-state": "im-state-admin-down"
              },
              {
                "interface-name": "GigabitEthernet0/0/0/4",
                "interface": "GigabitEthernet0/0/0/4",
                "state": "im-state-admin-down",
                "line-state": "im-state-admin-down"
              },
            ]
          }
        }
      }
    }
  }
}

B.2. Example of periodic updates using the new style update message.

The subscription was made on "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces", but for efficiency reasons, the device has split the subscription into separate child subscriptions for the different data providers, and makes use of the new message format.¶

Hence, this first periodic message is being published for the "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces/interface-summary" container, but it is encoded rooted relative to the schema for "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces".¶

{
  "ietf-notification:notification": {
    "eventTime": "2024-09-27T14:16:27.773Z",
    "ietf-yp-ext:update": {
      "id": 1,
      "subscription-path": "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces",
      "target-path":
        "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces/interface-summary",
      "snapshot-type": "periodic"
      "observation-time": "2024-09-27T14:16:27.773Z",
      "datastore-snapshot": {
        "interface-summary" : {
          "interface-type": [
            {
              "interface-type-name": "IFT_GETHERNET",
              "interface-type-description": "GigabitEthernet",
              "interface-counts": {
                "interface-count": 5,
                "up-interface-count": 2,
                "down-interface-count": 0,
                "admin-down-interface-count": 3
              }
            }
          ],
          "interface-counts": {
            "interface-count": 8,
            "up-interface-count": 5,
            "down-interface-count": 0,
            "admin-down-interface-count": 3
          }
        }
      }
    }
  }
}

The second periodic message is being published for the "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces/interfaces/interface" list, but again, it is encoded rooted relative to the schema for "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces". This message has a separate observation time that represents the more accurate time that this periodic date was read.¶

{
  "ietf-notification:notification": {
    "eventTime": "2024-09-27T14:16:27.973Z",
    "ietf-yp-ext:update": {
      "id": 1,
      "subscription-path": "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces",
      "target-path":
        "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces/interfaces/interface[]",
      "snapshot-type": "periodic"
      "observation-time": "2024-09-27T14:16:27.973Z",
      "datastore-snapshot": {
        "interfaces": {
          "interface": [
            {
              "interface-name": "GigabitEthernet0/0/0/0",
              "interface": "GigabitEthernet0/0/0/0",
              "state": "im-state-admin-down",
              "line-state": "im-state-admin-down"
            },
            {
              "interface-name": "GigabitEthernet0/0/0/4",
              "interface": "GigabitEthernet0/0/0/4",
              "state": "im-state-admin-down",
              "line-state": "im-state-admin-down"
            },
          ]
        }
      }
    }
  }
}

Each child subscription would use the same period and anchor time as the configured subscription, possibly with a little bit of initial jitter to avoid all daemons attempting to publish the data at exactly the same time.¶

B.3. Example of an on-change-update notification using the new style update message.

If the subscription is for on-change notifications, or periodic-and-on-change-notifications, then, if the interface state changed (specifically if the 'state' leaf of the interface changed state), and if the device was capable of generating on-change notifications, then you may see the following message. A few points of notes here:¶

• The on-change notification contains all of the state at the "target-path"¶

  • Not present in the below example, but if the notification excluded some state under an interfaces list entry (e.g., the line-state leaf) then this would logically represent the implicit deletion of that field under the given list entry.¶

  • In this example it is restricted to a single interface. It could also publish an on-change notification for all interfaces, by indicating a target-path without any keys specified. TODO - Can it represent notifications for a subset of interfaces?¶

• The schema of the change message is exactly the same as for the equivalent periodic message. It doesn't use the YANG Patch format [RFC8072] for on-change messages.¶

• The "observation time" leaf represents when the system first observed the on-change event occurring.¶

• The on-change event doesn't differentiate the type of change to operational state. The on-change-update snapshot type is used to indicate the creation of a new entry or some update to some existing state. Basically, the message can be thought of as the state existing with some current value.¶

{
  "ietf-notification:notification": {
    "eventTime": "2024-09-27T14:16:30.973Z",
    "ietf-yp-ext:update": {
      "id": 1,
      "subscription-path": "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces",
      "target-path":
        "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces/interfaces/
         interface[interface=GigabitEthernet0/0/0/0]",
      "snapshot-type": "on-change-update"
      "observation-time": "2024-09-27T14:16:30.973Z",
      "datastore-snapshot": {
        "interfaces": {
          "interface": [
            {
              "interface-name": "GigabitEthernet0/0/0/0",
              "interface": "GigabitEthernet0/0/0/0",
              "state": "im-state-up",
              "line-state": "im-state-up"
            }
          ]
        }
      }
    }
  }
}

B.4. Example of an on-change-delete notification using the new style update message.

If the interface was deleted, and if the system was capable of reporting on-change events for the delete event, then an on-change delete message would be encoded as per the following message. Of note:¶

• The on-change-delete snapshot type doesn't include a "datastore-snapshot", instead it represents a delete of the list entry at the path identified by the target-path, which is similar to a YANG Patch delete notification.¶

{
  "ietf-notification:notification": {
    "eventTime": "2024-09-27T14:16:40.973Z",
    "ietf-yp-ext:update": {
      "id": 1,
      "subscription-path": "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces",
      "target-path":
        "Cisco-IOS-XR-pfi-im-cmd-oper:interfaces/interfaces/
         interface[interface=GigabitEthernet0/0/0/0]",
      "snapshot-type": "on-change-delete"
      "observation-time": "2024-09-27T14:16:40.973Z",
    }
  }
}