Internet-Draft FANN YANG July 2026
Tantsura & Qu Expires 7 January 2027 [Page]
Workgroup:
Internet
Internet-Draft:
draft-tantsura-fann-yang-00
Published:
Intended Status:
Standards Track
Expires:
Authors:
J. Tantsura
Nvidia
Y. Qu
Futurewei Technologies

A YANG Data Model for Fast Network Notifications

Abstract

This document defines a YANG data model to Fast Network Notifictions.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 7 January 2027.

▲

Table of Contents

1. Overview

This document defines a YANG [RFC7950] data model for the support of fast network notifications.

The configuration in the model allows network operators to config the network conditions to generate notifications. For example, when a queue-depth reaches to a configured threshold. The grouping of "recipient" allows the configuration of various recipients so a notification can be sent to different recipients based on requirement, such as to a link or to a list of subsribers.

Notifications are sent when the configured conditions are met.

The meanings of the symbols in the YANG tree diagrams are defined in [RFC8340].

1.1. Requirements Language

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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. YANG Module for Fast Network Notifications

This document defines a YANG module to support fast network notifications.

module: ietf-fann
  +--rw fann
     +--rw fast-network-notification* [notification-id]
        +--rw notification-id               string
        +--rw source-id?                    inet:uri
        +--rw receivers
        |  +--rw (receiver)?
        |     +--:(link)
        |     |  +--rw link?              string
        |     +--:(path)
        |     |  +--rw path?              string
        |     +--:(domain)
        |     |  +--rw domain?            empty
        |     +--:(subscribe-nodes)
        |        +--rw subscribe-nodes*   inet:uri
        +--rw (condition)
           +--:(link-congestion)
           |  +--rw link?                   string
           |  +--rw utilization-level?      decimal64
           |  +--rw congestion-threshold?   uint8
           +--:(microburst)
           |  +--rw duration?               yang:timeticks
           |  +--rw intensity?              decimal64
           |  +--rw affected-resource?      string
           +--:(sla-violation)
           |  +--rw sla-reference?          string
           |  +--rw violated-metric?        string
           |  +--rw measured-value?         decimal64
           |  +--rw threshold?              decimal64
           +--:(queue-build-up)
           |  +--rw queue-id?               string
           |  +--rw depth?                  uint64
           |  +--rw queue-threshold?        uint8
           +--:(local-impairment)
              +--rw impairment-type?        string
              +--rw description?            string
              +--rw domain-id?              string
              +--rw node-id?                string
              +--rw path-id?                string
              +--rw link-id?                string

notifications:
    +---n fast-network-notification-event
       +--ro notification-id?   string
       +--ro timestamp          yang:date-and-time
       +--ro source-id?         inet:uri
       +--ro receivers
       |  +--ro (receiver)?
       |     +--:(link)
       |     |  +--ro link?              string
       |     +--:(path)
       |     |  +--ro path?              string
       |     +--:(domain)
       |     |  +--ro domain?            empty
       |     +--:(subscribe-nodes)
       |        +--ro subscribe-nodes*   inet:uri
       +--ro condition
          +--ro (condition-type)
             +--:(link-congestion)
             |  +--ro link?                string
             |  +--ro utilization-level?   decimal64
             +--:(microburst)
             |  +--ro duration?            yang:timeticks
             |  +--ro intensity?           decimal64
             |  +--ro affected-resource?   string
             +--:(sla-violation)
             |  +--ro sla-reference?       string
             |  +--ro violated-metric?     string
             |  +--ro measured-value?      decimal64
             +--:(queue-build-up)
             |  +--ro queue-id?            string
             |  +--ro depth?               uint64
             +--:(local-impairment)
                +--ro impairment-type?     string
                +--ro description?         string
                +--ro domain-id?           string
                +--ro node-id?             string
                +--ro path-id?             string
                +--ro link-id?             string

<CODE BEGINS> file "ietf-fann@2026-07-05.yang"

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

  import ietf-yang-types {
    prefix yang;
    reference "RFC 6991: Common YANG Data Types";
  }

  import ietf-inet-types {
    prefix inet;
    reference
      "RFC 6991: Common YANG Data Types";
  }

  organization
    "IETF FANN -  Fast Network Notifications Working Group";
  contact
    "WG Web:   https://datatracker.ietf.org/wg/fantel/
     WG List:  fann@ietf.org

     Author:    Yingzhen Qu
                <mailto:yingzhen.ietf@gmail.com>
     Author:    Jeff Tantsura
                <mailto:jeff.ietf@gmail.com>
     ";

  description
    "This YANG module defines fast notifications of fine-grained
     network status information. It structures real-time network
     condition data for dissemination to nodes and applications
     that perform traffic engineering, load balancing, flow control,
     and protection switching.

     Copyright (c) 2026 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).

     All revisions of IETF and IANA published modules can be found
     at the YANG Parameters registry group
     (https://www.iana.org/assignments/yang-parameters).

     This version of this YANG module is part of RFC XXXX; see
     the RFC itself for full legal notices.";

  revision 2026-07-05 {
    description
      "Initial revision.";
    reference
      "RFC XXXX: A YANG Data Model for Fast Network
       Notifications";
  }

  /*
   * Type definitions
   */

  typedef time-scale-type {
    type enumeration {
      enum microseconds {
        description
          "Time scale in microseconds.";
      }
      enum sub-millisecond {
        description
          "Time scale below one millisecond.";
      }
    }
    description
      "Granularity of the notification or condition in time.";
  }

  typedef notification-scope-type {
    type enumeration {
      enum link {
        description
          "Scope limited to a single link.";
      }
      enum path {
        description
          "Scope along a path.";
      }
      enum domain {
        description
          "Scope within a domain.";
      }
      enum subscribe {
        description
          "Scope based on subscription.";
      }
    }
    description
      "Scope of the fast network notification.";
  }

  typedef severity-level-type {
    type enumeration {
      enum low {
        description "Low severity.";
      }
      enum medium {
        description "Medium severity.";
      }
      enum high {
        description "High severity.";
      }
      enum critical {
        description "Critical severity.";
      }
    }
    description
      "Severity of the network condition.";
  }

  /*
   * Groupings
   */

  grouping network-location {
    description
      "Network location context for the notification or condition.";
    leaf domain-id {
      type string;
      description
        "Identifier of the domain.";
    }
    leaf node-id {
      type string;
      description
        "Node identifiers.";
    }
    leaf path-id {
      type string;
      description
        "Optional path identifier.";
    }
    leaf link-id {
      type string;
      description
        "Optional link identifier.";
    }
  }

  grouping recipient {
    container receivers {
      choice receiver {
        leaf link {
          type string;
          description
            "Uniquely identify the link where the notification
             will be sent to.";
        }
        leaf path {
          type string;
          description
            "Scope along a path.";
        }
        leaf domain {
          type empty;
          description
            "Scope within a domain.";
        }
        leaf-list subscribe-nodes {
          type inet:uri;
          description
            "List of recipient nodes based on subscription.";
        }
        description
          "Receivers of the fast network notification.";
      }
      description
        "Notification receivers.";
    }
    description
      "Target recipient of the fast network notification.";
  }

  grouping link-congestion {
    description "Link congestion condition.";
    leaf link {
      type string;
      description "Identifier of the congested link.";
    }
    leaf utilization-level {
      type decimal64 {
        fraction-digits 2;
        range "0..100";
      }
      units "percent";
      description "Link utilization level.";
    }
    leaf congestion-threshold {
      type uint8 {
        range "0..100";
      }
      units "percent";
      description
        "A configured threshold. A notification should be
         generated when the threshold is exceeded.";
    }
  }

  grouping microburst {
    description "Microburst condition.";
    leaf duration {
      type yang:timeticks;
      description "Duration of the microburst.";
    }
    leaf intensity {
      type decimal64 {
        fraction-digits 4;
      }
      description "Intensity metric of the microburst.";
    }
    leaf affected-resource {
      type string;
      description "Identifier of the affected resource.";
    }
  }

  grouping sla-violation {
    description "SLA violation condition.";
    leaf sla-reference {
      type string;
      description "Reference to the SLA that was violated.";
    }
    leaf violated-metric {
      type string;
      description "Type of metric that was violated.";
    }
    leaf measured-value {
      type decimal64 {
        fraction-digits 4;
      }
      description "Measured value that caused the violation.";
    }
    leaf threshold {
      type decimal64 {
        fraction-digits 4;
      }
      description "Threshold that was exceeded.";
    }
  }

  grouping queue-build-up {
    description "Queue build-up condition.";
    leaf queue-id {
      type string;
      description "Identifier of the queue.";
    }
    leaf depth {
      type uint64;
      description "Current queue depth (e.g., bytes or packets).";
    }
    leaf queue-threshold {
      type uint8 {
        range "0..100";
      }
      units "percent";
      description
        "A configured threshold. A notification should be
         generated when the threshold is exceeded.";
    }
  }

  grouping local-impairment {
    description "Local impairment condition.";
    leaf impairment-type {
      type string;
      description "Type of local impairment.";
    }
    leaf description {
      type string;
      description "Human-readable description of the impairment.";
    }
    uses network-location;
  }

  grouping network-condition-status {
    description
      "Structured network condition data. One of the condition types
       must be present.";
    choice condition-type {
      mandatory true;
      description "Type of network condition.";
      case link-congestion {
        leaf link {
          type string;
          description "Identifier of the congested link.";
        }
        leaf utilization-level {
          type decimal64 {
            fraction-digits 2;
            range "0..100";
          }
          units "percent";
          description "Link utilization level.";
        }
      }
      case microburst {
        uses microburst;
      }
      case sla-violation {
        leaf sla-reference {
          type string;
          description "Reference to the SLA that was violated.";
        }
        leaf violated-metric {
          type string;
          description "Type of metric that was violated.";
        }
        leaf measured-value {
          type decimal64 {
            fraction-digits 4;
          }
          description "Measured value that caused the violation.";
        }
      }
      case queue-build-up {
        leaf queue-id {
          type string;
          description "Identifier of the queue.";
        }
        leaf depth {
          type uint64;
          description "Current queue depth (e.g., bytes or packets).";
        }
      }
      case local-impairment {
        uses local-impairment;
      }
    }
  }

  grouping fast-network-notification {
    description
      "Fast network notification: on-demand, fine-grained network
       status information for prompt actions by recipients.";
    leaf notification-id {
      type string;
      description "Unique identifier of the notification.";
    }
    leaf timestamp {
      type yang:date-and-time;
      mandatory true;
      description "Time when the notification was generated.";
    }
    leaf source-id {
      type inet:uri;
      description
        "Identifier for a node, uniquely identifies a node.";
    }
    uses recipient;

    container condition {
      uses network-condition-status;
      description "Network condition conveyed by this notification.";
    }
  }

  /*
   * Configuration and status
   */

  container fann {
    description
      "Top-level container for FANN configuration and state.";

    list fast-network-notification {
      key "notification-id";
      description "A fast network notification entry.";
      leaf notification-id {
        type string;
        description "Unique identifier of the notification.";
      }

      leaf source-id {
        type inet:uri;
        description
          "Identifier for a node, uniquely identifies a node.";
      }

      uses recipient;

      choice condition {
        mandatory true;
        description "Type of network condition.";
        case link-congestion {
          uses link-congestion;
        }
        case microburst {
          uses microburst;
        }
        case sla-violation {
          uses sla-violation;
        }
        case queue-build-up {
          uses queue-build-up;
        }
        case local-impairment {
          uses local-impairment;
        }
      }
    }
  }

  /*
   * notification
   */

  notification fast-network-notification-event {
    description
      "Fast network notification event for real-time dissemination
       of fine-grained network status.";
    uses fast-network-notification;
  }
}

<CODE ENDS>

3. Security Considerations

This section is modeled after the template described in Section 3.7.1 of [RFC9907].

The YANG modules defined in this document are designed to be accessed via YANG-based management protocols, such as NETCONF [RFC6241] and RESTCONF [RFC8040]. These protocols have to use a secure transport layer (e.g., SSH [RFC4252], TLS [I-D.ietf-tls-rfc8446bis], and QUIC [RFC9000]) and have to use mutual authentication.

The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.

There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., "config true", which is the default). All writable data nodes are likely to be reasonably sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) and delete operations to these data nodes without proper protection or authentication can have a negative effect on network operations. The following subtrees and data nodes have particular sensitivities/vulnerabilities:

Some of the readable data nodes in the modules may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config, or notification) to these data nodes. The exposure of the network conditions will expose the detailed operaton state of the network. This may be undesirable since exposure may facilitate other attacks.

The notification defined in this document may reveal information about network status. Access to this notification SHOULD be restricted using NACM [RFC8341] to authorized management stations.

The YANG modules defined in this document do not include any RPC or action operations. Hence, there are no security considerations associated with these YANG constructs.

4. IANA Considerations

This document registers two URIs in the IETF XML registry [RFC3688]. Following the format in [RFC3688], the following registrations are requested:

   URI: urn:ietf:params:xml:ns:yang:ietf-fann
   Registrant Contact: The IESG.
   XML: N/A, the requested URI is an XML namespace.

This document registers the YANG modules in the YANG Module Names registry [RFC7950].

   name: ietf-fann
   Maintained by IANA?  N
   namespace: urn:ietf:params:xml:ns:yang:ietf-fann
   prefix: fann
   reference: RFC XXXX

5. Acknowledgements

TBD.

6. References

6.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688]
Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, , <https://www.rfc-editor.org/info/rfc3688>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/info/rfc7950>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341]
Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, , <https://www.rfc-editor.org/info/rfc8341>.

6.2. Informative References

[I-D.ietf-tls-rfc8446bis]
Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", Work in Progress, Internet-Draft, draft-ietf-tls-rfc8446bis-14, , <https://datatracker.ietf.org/doc/html/draft-ietf-tls-rfc8446bis-14>.
[RFC4252]
Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, , <https://www.rfc-editor.org/info/rfc4252>.
[RFC6241]
Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, , <https://www.rfc-editor.org/info/rfc6241>.
[RFC8040]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, , <https://www.rfc-editor.org/info/rfc8040>.
[RFC8340]
Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, , <https://www.rfc-editor.org/info/rfc8340>.
[RFC9000]
Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, , <https://www.rfc-editor.org/info/rfc9000>.
[RFC9907]
Bierman, A., Boucadair, M., Ed., and Q. Wu, "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 9907, DOI 10.17487/RFC9907, , <https://www.rfc-editor.org/info/rfc9907>.

Authors' Addresses

Jeff Tantsura
Nvidia
United States of America
Yingzhen Qu
Futurewei Technologies
United States of America