path: root/doc/rfc/rfc9418.txt

Internet Engineering Task Force (IETF)                         B. Claise
Request for Comments: 9418                                   J. Quilbeuf
Category: Standards Track                                         Huawei
ISSN: 2070-1721                                               P. Lucente
                                                                     NTT
                                                               P. Fasano
                                                               TIM S.p.A
                                                             T. Arumugam
                                                              Consultant
                                                               July 2023


                A YANG Data Model for Service Assurance

Abstract

   This document specifies YANG modules for representing assurance
   graphs.  These graphs represent the assurance of a given service by
   decomposing it into atomic assurance elements called subservices.
   The companion document, "Service Assurance for Intent-Based
   Networking Architecture" (RFC 9417), presents an architecture for
   implementing the assurance of such services.

   The YANG data models in this document conform to the Network
   Management Datastore Architecture (NMDA) defined in RFC 8342.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc9418.

Copyright Notice

   Copyright (c) 2023 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Revised BSD License text as described in Section 4.e of the
   Trust Legal Provisions and are provided without warranty as described
   in the Revised BSD License.

Table of Contents

   1.  Introduction
     1.1.  Terminology
   2.  YANG Modules Overview
   3.  Base IETF Service Assurance YANG Module
     3.1.  Concepts
     3.2.  Tree View
     3.3.  YANG Module
     3.4.  Rejecting Circular Dependencies
   4.  Guidelines for Defining New Subservice Types
   5.  Subservice Augmentation: "ietf-service-assurance-device" YANG
           Module
     5.1.  Tree View
     5.2.  Concepts
     5.3.  YANG Module
   6.  Subservice Augmentation: "ietf-service-assurance-interface"
           YANG Module
     6.1.  Tree View
     6.2.  Concepts
     6.3.  YANG Module
   7.  Security Considerations
   8.  IANA Considerations
     8.1.  The IETF XML Registry
     8.2.  The YANG Module Names Registry
   9.  References
     9.1.  Normative References
     9.2.  Informative References
   Appendix A.  Vendor-Specific Subservice Augmentation:
           "example-service-assurance-device-acme" YANG Module
     A.1.  Tree View
     A.2.  Concepts
     A.3.  YANG Module
   Appendix B.  Further Augmentations: IP Connectivity and IS-IS
           Subservices
     B.1.  IP Connectivity Module Tree View
     B.2.  IS-IS Module Tree View
     B.3.  Global Tree View
     B.4.  IP Connectivity YANG Module
     B.5.  IS-IS YANG Module
   Appendix C.  Example of a YANG Instance
   Appendix D.  YANG Library for Service Assurance
   Acknowledgements
   Authors' Addresses

1.  Introduction

   [RFC9417] describes an architecture and a set of involved components
   for service assurance, called Service Assurance for Intent-based
   Networking (SAIN).  This document complements the architecture by
   specifying a data model for the interfaces between components.  More
   specifically, the document provides YANG modules for the purpose of
   service assurance in a format that is:

   *  machine readable,

   *  vendor independent, and

   *  augmentable such that SAIN agents from Figure 1 of [RFC9417] can
      support and expose new subservices to SAIN orchestrators and
      collectors.

1.1.  Terminology

   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.

   The terms used in this document are defined in [RFC9417].

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

2.  YANG Modules Overview

   The main YANG module, "ietf-service-assurance" (Section 3), defines
   objects for assuring network services based on their decomposition
   into so-called subservices.  The subservices are hierarchically
   organized by dependencies.  The subservices, along with the
   dependencies, constitute an assurance graph.  This module should be
   supported by an agent that is able to interact with the devices in
   order to produce the health statuses and symptoms for each subservice
   in an assurance graph.  This module is intended for the following use
   cases:

   *  Assurance graph configuration:

      -  Subservices: Configure a set of subservices to assure by
         specifying their types and parameters.

      -  Dependencies: Configure the dependencies between the
         subservices, along with their types.

   *  Assurance telemetry: Export the assurance graph with health
      statuses and symptoms for each node.

   The module is also intended to be exported by the SAIN collector that
   aggregates the output of several SAIN agents to provide the global
   assurance graph.  In that case, only the telemetry export use case is
   considered.

   The modules presented in this document conform to the Network
   Management Datastore Architecture (NMDA) defined in [RFC8342].

   The second YANG module, "ietf-service-assurance-device" (Section 5),
   augments the "ietf-service-assurance" module by adding support for
   the device subservice.  Additional subservice types might be added
   following a similar approach.

   The third YANG module, "ietf-service-assurance-interface"
   (Section 6), augments the "ietf-service-assurance" module as well by
   adding support for the interface subservice.

   We provide additional examples in the appendix.  The module "example-
   service-assurance-device-acme" (Appendix A) augments the "ietf-
   service-assurance-device" module to customize it for devices of the
   fictional Acme Corporation.  Additional vendor-specific parameters
   might be added following a similar approach.  We also provide the
   modules "example-service-assurance-ip-connectivity" and "example-
   service-assurance-is-is" (Appendix B) to model the example in
   Figure 2 from Section 3.1 of [RFC9417].

3.  Base IETF Service Assurance YANG Module

3.1.  Concepts

   The "ietf-service-assurance" YANG module assumes a set of subservices
   to be assured independently.  A subservice is a feature or a subpart
   of the network system that a given service instance depends on.
   Examples of subservice types include the following:

   *  device: Whether a device is healthy, and if not, what are the
      symptoms?  Such a subservice might monitor the device resources,
      such as CPU, RAM, or Ternary Content-Addressable Memory (TCAM).
      Potential symptoms are "CPU overloaded", "Out of RAM", or "Out of
      TCAM".

   *  ip-connectivity: Given two IP addresses bound to two devices, what
      is the quality of the IP connectivity between them?  Potential
      symptoms are "No route available" or "Equal-Cost Multipaths
      (ECMPs) imbalance".

   An instance of the device subservice is representing a subpart of the
   network system, namely a specific device.  An instance of the ip-
   connectivity subservice is representing a feature of the network,
   namely the connectivity between two specific IP addresses on two
   devices.  In both cases, these subservices might depend on other
   subservices, for instance, the connectivity might depend on a
   subservice representing the routing system and on a subservice
   representing ECMPs.

   The two example subservices presented above need different sets of
   parameters to fully characterize one of their instances.  An instance
   of the device subservice is fully characterized by a single parameter
   allowing to identify the device to monitor.  For the ip-connectivity
   subservice, at least the device and IP address for both ends of the
   link are needed to fully characterize an instance.

   The base model presented in this section specifies a single type of
   subservice, which represents service instances.  Such nodes play a
   particular role in the assurance graph because they represent the
   starting point, or root, for the assurance graph of the corresponding
   service instance.  The parameters required to fully identify a
   service instance are the name of the service and the name of the
   service instance.  To support other types of subservices, such as
   device or ip-connectivity, the "ietf-service-assurance" module is
   intended to be augmented.

   The dependencies are modeled as a list, i.e., each subservice
   contains a list of references to its dependencies.  That list can be
   empty if the subservice instance does not have any dependencies.

   By specifying service instances and their dependencies in terms of
   subservices, one defines a global assurance graph.  That assurance
   graph is the result of merging all the individual assurance graphs
   for the assured service instances.  Each subservice instance is
   expected to appear only once in the global assurance graph even if
   several service instances depend on it.  For example, an instance of
   the device subservice is a dependency of every service instance that
   relies on the corresponding device.  The assurance graph of a
   specific service instance is the subgraph obtained by traversing the
   global assurance graph through the dependencies, starting from the
   specific service instance.

   An assurance agent configured with such a graph is expected to
   produce, for each configured subservice, a health status that
   indicates how healthy the subservice is.  If the subservice is not
   healthy, the agent is expected to produce a list of symptoms
   explaining why the subservice is not healthy.

3.2.  Tree View

   The following tree diagram [RFC8340] provides an overview of the
   "ietf-service-assurance" module.

   module: ietf-service-assurance
     +--ro assurance-graph-last-change    yang:date-and-time
     +--rw subservices
     |  +--rw subservice* [type id]
     |     +--rw type                                identityref
     |     +--rw id                                  string
     |     +--ro last-change?                        yang:date-and-time
     |     +--ro label?                              string
     |     +--rw under-maintenance!
     |     |  +--rw contact    string
     |     +--rw (parameter)
     |     |  +--:(service-instance-parameter)
     |     |     +--rw service-instance-parameter
     |     |        +--rw service          string
     |     |        +--rw instance-name    string
     |     +--ro health-score                        int8
     |     +--ro symptoms-history-start?             yang:date-and-time
     |     +--ro symptoms
     |     |  +--ro symptom* [start-date-time agent-id symptom-id]
     |     |     +--ro symptom-id             leafref
     |     |     +--ro agent-id               -> /agents/agent/id
     |     |     +--ro health-score-weight?   uint8
     |     |     +--ro start-date-time        yang:date-and-time
     |     |     +--ro stop-date-time?        yang:date-and-time
     |     +--rw dependencies
     |        +--rw dependency* [type id]
     |           +--rw type
     |           |       -> /subservices/subservice/type
     |           +--rw id                 leafref
     |           +--rw dependency-type?   identityref
     +--ro agents
     |  +--ro agent* [id]
     |     +--ro id          string
     |     +--ro symptoms* [id]
     |        +--ro id             string
     |        +--ro description    string
     +--ro assured-services
        +--ro assured-service* [service]
           +--ro service      leafref
           +--ro instances* [name]
              +--ro name           leafref
              +--ro subservices* [type id]
                 +--ro type    -> /subservices/subservice/type
                 +--ro id      leafref

   The date of the last change in "assurance-graph-last-change" is read
   only.  It must be updated each time the graph structure is changed by
   addition or deletion of subservices and dependencies or modifications
   of their configurable attributes, including their maintenance
   statuses.  Such modifications correspond to a structural change in
   the graph.  The date of the last change is useful for a client to
   quickly check if there is a need to update the graph structure.  A
   change in the health score or symptoms associated to a service or
   subservice does not change the structure of the graph, and thus has
   no effect on the date of the last change.

   The "subservices" list contains all the subservice instances
   currently known by the server (i.e., SAIN agent or SAIN collector).
   A subservice declaration MUST provide the following:

   *  a subservice type ("type"): a reference to an identity that
      inherits from "subservice-base", which is the base identity for
      any subservice type

   *  an id ("id"): a string uniquely identifying the subservice among
      those with the same type

   The type and id uniquely identify a given subservice.

   The "last-change" indicates when the dependencies or maintenance
   status of this particular subservice were last modified.

   The "label" is a human-readable description of the subservice.

   The presence of the "under-maintenance" container inhibits the
   emission of symptoms for the subservice and subservices that depend
   on them.  In that case, a "contact" MUST be provided to indicate who
   or which software is responsible for the maintenance.  See
   Section 3.6 of [RFC9417] for a more detailed discussion.

   The "parameter" choice is intended to be augmented in order to
   describe parameters that are specific to the current subservice type.
   This base module defines only the subservice type representing
   service instances.  Service instances MUST be modeled as a particular
   type of subservice with two parameters: "service" and "instance-
   name".  The "service" parameter is the name of the service defined in
   the network orchestrator, for instance, "point-to-point-l2vpn".  The
   "instance-name" parameter is the name assigned to the particular
   instance to be assured, for instance, the name of the customer using
   that instance.

   The "health-score" contains a value normally between 0 and 100,
   indicating how healthy the subservice is.  As mentioned in the health
   score definition, the special value -1 can be used to specify that no
   value could be computed for that health score, for instance, if some
   metric needed for that computation could not be collected.

   The "symptoms-history-start" is the cutoff date for reporting
   symptoms.  Symptoms that were terminated before that date are not
   reported anymore in the model.

   The status of each subservice contains a list of symptoms.  Each
   symptom is specified by:

   *  an identifier "symptom-id", which identifies the symptom locally
      to an agent,

   *  an agent identifier "agent-id", which identifies the agent raising
      the symptom,

   *  a "health-score-weight" specifying the impact to the health score
      incurred by this symptom,

   *  a "start-date-time" indicating when the symptom became active, and

   *  a "stop-date-time" indicating when the symptom stopped being
      active (this field is not present if the symptom is still active).

   In order for the pair "agent-id" and "symptom-id" to uniquely
   identify a symptom, the following is necessary:

   *  "agent-id" MUST be unique among all agents of the system.

   *  "symptom-id" MUST be unique among all symptoms raised by the
      agent.

   Note that "agent-id" and "symptom-id" are leafrefs pointing to the
   objects defined later in the document.  While the combination of
   "symptom-id" and "agent-id" is sufficient as a unique key list, the
   "start-date-time" second key helps to sort and retrieve relevant
   symptoms.

   The "dependency" list contains the dependencies for the current
   subservice.  Each of them is specified by a leafref to both "type"
   and "id" of the target dependencies.  A dependency has a type
   indicated in the "dependency-type" field.  Two types are specified in
   the model:

   *  Impacting: Such a dependency indicates an impact on the health of
      the dependent.

   *  Informational: Such a dependency might explain why the dependent
      has issues but does not impact its health.

   To illustrate the difference between "impacting" and "informational",
   consider the interface subservice representing a network interface.
   If the device to which the network interface belongs goes down, the
   network interface will transition to a "down" state as well.
   Therefore, the dependency of the interface subservice towards the
   device subservice is "impacting".  On the other hand, a dependency
   towards the ecmp-load subservice, which checks that the load between
   ECMPs remains stable throughout time, is only "informational".
   Indeed, services might be perfectly healthy even if the load
   distribution between ECMPs changed.  However, such an instability
   might be a relevant symptom for diagnosing the root cause of a
   problem.

   Within the container "agents", the list "agent" contains the list of
   symptoms per agent.  The key of the list is the "id", which MUST be
   unique among agents of a given assurance system.  For each agent, the
   list "symptoms-description" maps an "id" to its "description".  The
   "id" MUST be unique among the symptoms raised by the agent.

   Within the container "assured-services", the list "assured-service"
   contains the subservices indexed by assured service instances.  For
   each service type identified by the "service" leaf, all instances of
   that service are listed in the "instances" list.  For each instance
   identified by the "name" leaf, the "subservices" list contains all
   descendant subservices that are part of the assurance graph for that
   specific instance.  These imbricated lists provide a query
   optimization to get the list of subservices in that assurance graph
   in a single query instead of recursively querying the dependencies of
   each subservice, starting from the node representing the service
   instance.

   The relation between the health score ("health-score") and the
   "health-score-weight" of the currently active symptoms is not
   explicitly defined in this document.  The only requirement is that a
   health score that is strictly smaller than 100 (the maximal value)
   must be explained by at least one symptom.  A way to enforce that
   requirement is to first detect symptoms and then compute the health
   score based on the "health-score-weight" of the detected symptoms.
   As an example, such a computation could be to sum the "health-score-
   weight" of the active symptoms, subtract that value from 100, and
   change the value to 0 if the result is negative.  The relation
   between health score and "health-score-weight" is left to the
   implementor (of an agent [RFC9417]).

   Keeping the history of the graph structure is out of scope for this
   YANG module.  Only the current version of the assurance graph can be
   fetched.  In order to keep the history of the graph structure, some
   time-series database (TSDB) or similar storage must be used.

3.3.  YANG Module

   This model contains references to [RFC6991].

   <CODE BEGINS> file "ietf-service-assurance@2023-07-11.yang"
   module ietf-service-assurance {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance";
     prefix sain;

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

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
        WG List:  <mailto:opsawg@ietf.org>
        Author:   Benoit Claise  <mailto:benoit.claise@huawei.com>
        Author:   Jean Quilbeuf   <mailto:jean.quilbeu@huawei.com>";
     description
       "This module defines objects for assuring services based on their
        decomposition into so-called subservices, according to the
        Service Assurance for Intent-based Networking (SAIN)
        architecture.

        The subservices hierarchically organized by dependencies
        constitute an assurance graph.  This module should be supported
        by an assurance agent that is able to interact with the devices
        in order to produce the health status and symptoms for each
        subservice in the assurance graph.

        This module is intended for the following use cases:
        * Assurance graph configuration:
          - Subservices: Configure a set of subservices to assure by
            specifying their types and parameters.
          - Dependencies: Configure the dependencies between the
            subservices, along with their type.
        * Assurance telemetry: Export the health statuses of the
          subservices, along with the observed symptoms.

        Copyright (c) 2023 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 9418; see the
        RFC itself for full legal notices.  ";

     revision 2023-07-11 {
       description
         "Initial version.";
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     identity subservice-base {
       description
         "Base identity for subservice types.";
     }

     identity service-instance-type {
       base subservice-base;
       description
         "Specific type of subservice that represents a service
          instance.  Instance of this type will depend on other
          subservices to build the top of the assurance graph.";
     }

     identity dependency-type {
       description
         "Base identity for representing dependency types.";
     }

     identity informational {
       base dependency-type;
       description
         "Indicates that symptoms of the dependency might be of interest
          for the dependent, but the status of the dependency should not
          have any impact on the dependent.";
     }

     identity impacting {
       base dependency-type;
       description
         "Indicates that the status of the dependency directly impacts
          the status of the dependent.";
     }

     grouping subservice-reference {
       description
         "Reference to a specific subservice identified by its type and
          identifier.  This grouping is only for internal use in this
          module.";
       leaf type {
         type leafref {
           path "/subservices/subservice/type";
         }
         description
           "The type of the subservice to refer to (e.g., device).";
       }
       leaf id {
         type leafref {
           path "/subservices/subservice[type=current()/../type]/id";
         }
         description
           "The identifier of the subservice to refer to.";
       }
     }

     grouping subservice-dependency {
       description
         "Represents a dependency to another subservice.  This grouping
          is only for internal use in this module";
       uses subservice-reference;
       leaf dependency-type {
         type identityref {
           base dependency-type;
         }
         description
           "Represents the type of dependency (e.g., informational or
            impacting).";
       }
     }

     leaf assurance-graph-last-change {
       type yang:date-and-time;
       config false;
       mandatory true;
       description
         "Time and date at which the assurance graph last changed after
          any structural changes (dependencies and/or maintenance
          windows parameters) are applied to the subservice(s).  The
          time and date must be the same or more recent than the most
          recent value of any changed subservices last-change time and
          date.";
     }
     container subservices {
       description
         "Root container for the subservices.";
       list subservice {
         key "type id";
         description
           "List of configured subservices.";
         leaf type {
           type identityref {
             base subservice-base;
           }
           description
             "Type of the subservice identifying the type of the part
              or functionality that is being assured by this list
              entry, for instance, interface, device, or
              ip-connectivity.";
         }
         leaf id {
           type string;
           description
             "Identifier of the subservice instance.  Must be unique
              among subservices of the same type.";
         }
         leaf last-change {
           type yang:date-and-time;
           config false;
           description
             "Date and time at which the structure for this
              subservice instance last changed, i.e., dependencies
              and/or maintenance windows parameters.";
         }
         leaf label {
           type string;
           config false;
           description
             "Label of the subservice, i.e., text describing what the
              subservice is to be displayed on a human interface.

              It is not intended for random end users but for
              network/system/software engineers that are able to
              interpret it.  Therefore, no mechanism for language
              tagging is needed.";
         }
         container under-maintenance {
           presence "true";
           description
             "The presence of this container indicates that the current
              subservice is under maintenance.";
           leaf contact {
             type string;
             mandatory true;
             description
               "A string used to model an administratively assigned name
                of the resource that is performing maintenance.

                It is suggested that this freeform field, which could be
                a URI, contains one or more of the following: IP
                address, management station name, network manager's
                name, location, and/or phone number.  It might even
                contain the expected maintenance time.

                In some cases, the agent itself will be the owner of an
                entry.  In these cases, this string shall be set to a
                string starting with 'monitor'.";
           }
         }
         choice parameter {
           mandatory true;
           description
             "Specify the required parameters per subservice type.  Each
              module augmenting this module with a new subservice type
              that is a new identity based on subservice-base should
              augment this choice as well by adding a container
              available only if the current subservice type is
              the newly added identity.";
           container service-instance-parameter {
             when "derived-from-or-self(../type,
                   'sain:service-instance-type')";
             description
               "Specify the parameters of a service instance.";
             leaf service {
               type string;
               mandatory true;
               description
                 "Name of the service.";
             }
             leaf instance-name {
               type string;
               mandatory true;
               description
                 "Name of the instance for that service.";
             }
           }
           // Other modules can augment their own cases into here.
         }
         leaf health-score {
           type int8 {
             range "-1 .. 100";
           }
           config false;
           mandatory true;
           description
             "Score value of the subservice health.  A value of 100
              means that the subservice is healthy.  A value of 0 means
              that the subservice is broken.  A value between 0 and 100
              means that the subservice is degraded. The special value
              -1 means that the health score could not be computed.";
         }
         leaf symptoms-history-start {
           type yang:date-and-time;
           config false;
           description
             "Date and time at which the symptom's history starts for
              this subservice instance, either because the subservice
              instance started at that date and time or because the
              symptoms before that were removed due to a garbage
              collection process.";
         }
         container symptoms {
           config false;
           description
             "Symptoms for the subservice.";
           list symptom {
             key "start-date-time agent-id symptom-id";
             unique "agent-id symptom-id";
             description
               "List of symptoms of the subservice.  While the
                start-date-time key is not necessary per se, this would
                get the entries sorted by start-date-time for easy
                consumption.";
             leaf symptom-id {
               type leafref {
                 path "/agents/agent[id=current()/../agent-id]"
                    + "/symptoms/id";
               }
               description
                 "Identifier of the symptom to be interpreted according
                  to the agent identified by the agent-id.";
             }
             leaf agent-id {
               type leafref {
                 path "/agents/agent/id";
               }
               description
                 "Identifier of the agent raising the current symptom.";
             }
             leaf health-score-weight {
               type uint8 {
                 range "0 .. 100";
               }
               description
                 "The weight to the health score incurred by this
                  symptom.  The higher the value, the more of an impact
                  this symptom has.  If a subservice health score is not
                  100, there must be at least one symptom with a
                  health-score-weight larger than 0.";
             }
             leaf start-date-time {
               type yang:date-and-time;
               description
                 "Date and time at which the symptom was detected.";
             }
             leaf stop-date-time {
               type yang:date-and-time;
               description
                 "Date and time at which the symptom stopped being
                  detected.  Must be after the start-date-time.  If the
                  symptom is ongoing, this field should not be
                  populated.";
             }
           }
         }
         container dependencies {
           description
             "Indicates the set of dependencies of the current
              subservice, along with their types.";
           list dependency {
             key "type id";
             description
               "List of dependencies of the subservice.";
             uses subservice-dependency;
           }
         }
       }
     }
     container agents {
       config false;
       description
         "Container for the list of agents' symptoms.";
       list agent {
         key "id";
         description
           "Contains symptoms of each agent involved in computing the
            health status of the current graph.  This list acts as a
            glossary for understanding the symptom ids returned by each
            agent.";
         leaf id {
           type string;
           description
             "Id of the agent for which we are defining the symptoms.
              This identifier must be unique among all agents.";
         }
         list symptoms {
           key "id";
           description
             "List of symptoms raised by the current agent that is
              identified by the symptom-id.";
           leaf id {
             type string;
             description
               "Id of the symptom for the current agent.  The agent must
                guarantee the unicity of this identifier.";
           }
           leaf description {
             type string;
             mandatory true;
             description
               "Description of the symptom, i.e., text describing what
                the symptom is, is to be computer consumable and
                displayed on a human interface.

                It is not intended for random end users but for
                network/system/software engineers that are able to
                interpret it.  Therefore, no mechanism for language
                tagging is needed.";
           }
         }
       }
     }
     container assured-services {
       config false;
       description
         "Container for the index of assured services.";
       list assured-service {
         key "service";
         description
           "Service instances that are currently part of the assurance
            graph.  The list must contain an entry for every service
            that is currently present in the assurance graph.  This list
            presents an alternate access to the graph stored in
            subservices that optimizes querying the assurance graph of
            a specific service instance.";
         leaf service {
           type leafref {
             path "/subservices/subservice/service-instance-parameter/"
                + "service";
           }
           description
             "Name of the service.";
         }
         list instances {
           key "name";
           description
             "Instances of the service. The list must contain
              an entry for every instance of the parent service.";
           leaf name {
             type leafref {
               path "/subservices/subservice/service-instance-parameter"
                  + "/instance-name";
             }
             description
               "Name of the service instance.  The leafref must point to
                a service-instance-parameter whose service leaf matches
                the parent service.";
           }
           list subservices {
             key "type id";
             description
               "Subservices that appear in the assurance graph of the
                current service instance.

                The list must contain the subservice corresponding to
                the service instance, i.e., the subservice that
                matches the service and instance-name keys.

                For every subservice in the list, all subservices listed
                as dependencies must also appear in the list.";
             uses subservice-reference;
           }
         }
       }
     }
   }
   <CODE ENDS>

3.4.  Rejecting Circular Dependencies

   The statuses of services and subservices depend on the statuses of
   their dependencies, and thus circular dependencies between them
   prevent the computation of statuses.  Section 3.1.1 of the SAIN
   architecture document [RFC9417] discusses how such dependencies
   appear and how they could be removed.  The responsibility of avoiding
   such dependencies falls to the SAIN orchestrator.  However, we
   specify in this section the expected behavior when a server
   supporting the "ietf-service-assurance" module receives a data
   instance containing circular dependencies.

   Enforcing the absence of circular dependencies as a YANG constraint
   falls back to implementing a graph traversal algorithm with XPath and
   checking that the current node is not reachable from its
   dependencies.  Even with such a constraint, there is no guarantee
   that merging two graphs without dependency loops will result in a
   graph without dependency loops.  Indeed, Section 3.1.1 of [RFC9417]
   presents an example where merging two graphs without dependency loops
   results in a graph with a dependency loop.

   Therefore, a server implementing the "ietf-service-assurance" module
   MUST check that there is no dependency loop whenever the graph is
   modified.  A modification creating a dependency loop MUST be
   rejected.

4.  Guidelines for Defining New Subservice Types

   The base YANG module defined in Section 3.3 only defines a single
   type of subservice that represent service instances.  As explained
   above, this model is meant to be augmented so that a variety of
   subservices can be used in the assurance graph.  In this section, we
   propose some guidelines for specifying such extensions at IETF.

   The mechanism to add a new subservice type is to define a new module
   for that subservice.  The module name should start with "ietf-
   service-assurance-".  The namespace of the module should start with
   "urn:ietf:params:xml:ns:yang:ietf-service-assurance-".  The prefix of
   the module should start with "sain-".  For instance, the subservice
   type representing the assurance of a device should have:

   *  the name "ietf-service-assurance-device",

   *  the namespace "urn:ietf:params:xml:ns:yang:ietf-service-assurance-
      device", and

   *  the prefix "sain-device".

   The new module should define:

   *  a new identity to represent the new type and

   *  the parameters fully specifying an instance of the new subservice
      type.

   The new identity should be based on the "subservice-base" identity.
   The name of the identity should end with "-type", for instance,
   "device-type".

   The parameters should be defined in a container named "parameters"
   that augments the choice "/subservices/subservice/parameter" from the
   main module.  The augmentation should be restricted to cases where
   the type of the subservice matches the identity representing the new
   service type.

   We define two subservice types in the next sections: the "device"
   subservice type is defined in Section 5 and the "interface"
   subservice type is defined is Section 6.  These subservices can be
   taken as examples of the rules defined in this section.

   Vendors can specify their own subservices types by defining the
   corresponding modules in their own namespace.  An example of such a
   vendor-specific module is specified in Appendix A.  Vendors can also
   augment existing IETF-specified subservices to add their own vendor-
   specific information.

5.  Subservice Augmentation: "ietf-service-assurance-device" YANG Module

5.1.  Tree View

   The following tree diagram [RFC8340] provides an overview of the
   "ietf-service-assurance-device" module.

   module: ietf-service-assurance-device

     augment /sain:subservices/sain:subservice/sain:parameter:
       +--rw parameters
          +--rw device    string

   A complete tree view of the base module with all augmenting modules
   presented in this document is available in Appendix B.3.

5.2.  Concepts

   As the number of subservices will grow over time, the YANG module is
   designed to be extensible.  A new subservice type requires the
   precise specifications of its type and expected parameters.  Let us
   illustrate the example of the new device subservice type.  As the
   name implies, it monitors and reports the device health, along with
   some symptoms in case of degradation.

   For our device subservice definition, the new identity "device-type"
   is specified as an inheritance from the base identity for
   subservices.  This indicates to the assurance agent that we are now
   assuring the health of a device.

   The typical parameter for the configuration of the device subservice
   is the name of the device that we want to assure.  By augmenting the
   parameter choice from the "ietf-service-assurance" YANG module for
   the case of the "device-type" subservice type, this new parameter is
   specified.

5.3.  YANG Module

   <CODE BEGINS> file "ietf-service-assurance-device@2023-07-11.yang"
   module ietf-service-assurance-device {
     yang-version 1.1;
     namespace
       "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device";
     prefix sain-device;

     import ietf-service-assurance {
       prefix sain;
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
        WG List:  <mailto:opsawg@ietf.org>
        Author:   Benoit Claise  <mailto:benoit.claise@huawei.com>
        Author:   Jean Quilbeuf   <mailto:jean.quilbeuf@huawei.com>";
     description
       "This module augments the ietf-service-assurance module with
        support of the device subservice.

        Copyright (c) 2023 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 9418; see the
        RFC itself for full legal notices.  ";

     revision 2023-07-11 {
       description
         "Initial revision.";
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     identity device-type {
       base sain:subservice-base;
       description
         "Identity of device subservice.";
     }

     augment "/sain:subservices/sain:subservice/sain:parameter" {
       when "derived-from-or-self(sain:type, 'device-type')";
       description
         "Augments the parameter choice from the ietf-service-assurance
          module with a case specific to the device subservice.";
       container parameters {
         description
           "Parameters for the device subservice type.";
         leaf device {
           type string;
           mandatory true;
           description
             "Identifier of the device to monitor. The
              identifier (e.g., device id, hostname, or management IP)
              depends on the context.";
         }
       }
     }
   }
   <CODE ENDS>

6.  Subservice Augmentation: "ietf-service-assurance-interface" YANG
    Module

6.1.  Tree View

   The following tree diagram [RFC8340] provides an overview of the
   "ietf-service-assurance-interface" data model.

   module: ietf-service-assurance-interface

     augment /sain:subservices/sain:subservice/sain:parameter:
       +--rw parameters
          +--rw device       string
          +--rw interface    string

   A complete tree view of the base module with all augmenting modules
   presented in this document is available in Appendix B.3.

6.2.  Concepts

   For the interface subservice definition, the new interface-type is
   specified as an inheritance from the base identity for subservices.
   This indicates to the assurance agent that we are now assuring the
   health of an interface.

   The parameters for the configuration of the interface subservice are
   the name of the device and, on that specific device, a specific
   interface.  These parameters are aligned with the "ietf-interfaces"
   model described in [RFC8343], where the name of the interface is the
   only key needed to identify an interface on a given device.  By
   augmenting the parameter choice from the "ietf-service-assurance"
   YANG module for the case of the interface-type subservice type, those
   two new parameters are specified.

6.3.  YANG Module

   <CODE BEGINS> file "ietf-service-assurance-interface@2023-07-11.yang"
   module ietf-service-assurance-interface {
     yang-version 1.1;
     namespace
       "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface";
     prefix sain-interface;

     import ietf-service-assurance {
       prefix sain;
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
        WG List:  <mailto:opsawg@ietf.org>
        Author:   Benoit Claise  <mailto:benoit.claise@huawei.com>
        Author:   Jean Quilbeuf   <mailto:jean.quilbeuf@huawei.com>";
     description
       "This module extends the ietf-service-assurance module to add
        support for the interface subservice.

        It checks whether an interface is healthy.

        Copyright (c) 2023 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 9418; see the
        RFC itself for full legal notices.  ";

     revision 2023-07-11 {
       description
         "Initial revision.";
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     identity interface-type {
       base sain:subservice-base;
       description
         "Checks whether an interface is healthy.";
     }

     augment "/sain:subservices/sain:subservice/sain:parameter" {
       when "derived-from-or-self(sain:type, 'interface-type')";
       description
         "Augments the parameter choice from ietf-service-assurance
          module with a case specific to the interface subservice.";
       container parameters {
         description
           "Parameters for the interface subservice type.";
         leaf device {
           type string;
           mandatory true;
           description
             "Device supporting the interface.";
         }
         leaf interface {
           type string;
           mandatory true;
           description
             "Name of the interface.";
         }
       }
     }
   }
   <CODE ENDS>

7.  Security Considerations

   The YANG modules specified in this document define schema for data
   that is designed to be accessed via network management protocols such
   as NETCONF [RFC6241] or RESTCONF [RFC8040].  The lowest NETCONF layer
   is the secure transport layer, and the mandatory-to-implement secure
   transport is Secure Shell (SSH) [RFC6242].  The lowest RESTCONF layer
   is HTTPS, and the mandatory-to-implement secure transport is TLS
   [RFC8446].

   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 these YANG modules that
   are writable/creatable/deletable (i.e., config true, which is the
   default).  These data nodes may be considered sensitive or vulnerable
   in some network environments.  Write operations (e.g., edit-config)
   to these data nodes without proper protection can have a negative
   effect on network operations.  These are the subtrees and data nodes
   and their sensitivity/vulnerability:

   *  /subservices/subservice : By modifying this subtree, one can
      modify the structure of the assurance graph, which could alter the
      status of the services reported by the assurance framework.  On
      one hand, modifications can cause the assurance system to report a
      service as broken when it is actually healthy (false positive),
      resulting in engineers or automation software losing time and
      potentially causing real issues by doing unnecessary modifications
      on the network.  On the other hand, modifications could prevent
      the assurance system from reporting actual issues (false
      negative), resulting in failures that could have been avoided.
      Depending on the service, the impact of these avoidable failures
      could be Service-Level Agreement (SLA) violations fees or
      disruption of emergency calls.

   Some readable data nodes in these YANG 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.  These are the subtrees and data
   nodes and their sensitivity/vulnerability:

   *  /subservices/subservice

   *  /agents/agent

   *  /assured-services/assured-service

   Each of these subtrees contains information about services,
   subservices, or possible symptoms raised by the agents.  The
   information contained in this subtree might give information about
   the underlying network as well as services deployed for the
   customers.  For instance, a customer might be given access to monitor
   their services status (e.g., via model-driven telemetry).  In that
   example, the customer access should be restricted to nodes
   representing their services so as not to divulge information about
   the underlying network structure or others customers services.

8.  IANA Considerations

8.1.  The IETF XML Registry

   IANA has registered the following three URIs in the "IETF XML
   Registry" [RFC3688]:

   URI:  urn:ietf:params:xml:ns:yang:ietf-service-assurance
   Registrant Contact:  The OPSAWG WG of the IETF.
   XML:  N/A; the requested URI is an XML namespace.

   URI:  urn:ietf:params:xml:ns:yang:ietf-service-assurance-device
   Registrant Contact:  The OPSAWG WG of the IETF.
   XML:  N/A; the requested URI is an XML namespace.

   URI:  urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface
   Registrant Contact:  The OPSAWG WG of the IETF.
   XML:  N/A; the requested URI is an XML namespace.

8.2.  The YANG Module Names Registry

   IANA has registered the following three YANG modules in the "YANG
   Module Names" registry [RFC7950]:

   name:  ietf-service-assurance
   namespace:  urn:ietf:params:xml:ns:yang:ietf-service-assurance
   prefix:  sain
   reference:  RFC 9418

   name:  ietf-service-assurance-device
   namespace:  urn:ietf:params:xml:ns:yang:ietf-service-assurance-device
   prefix:  sain-device
   reference:  RFC 9418

   name:  ietf-service-assurance-interface
   namespace:  urn:ietf:params:xml:ns:yang:ietf-service-assurance-
      interface
   prefix:  sain-interface
   reference:  RFC 9418

   These modules are not maintained by IANA.

9.  References

9.1.  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/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.

   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
              <https://www.rfc-editor.org/info/rfc6242>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013,
              <https://www.rfc-editor.org/info/rfc6991>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [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/info/rfc8174>.

   [RFC8341]  Bierman, A. and M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/info/rfc8341>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

   [RFC9417]  Claise, B., Quilbeuf, J., Lopez, D., Voyer, D., and T.
              Arumugam, "Service Assurance for Intent-Based Networking
              Architecture", RFC 9417, DOI 10.17487/RFC9417, July 2023,
              <https://www.rfc-editor.org/info/rfc9417>.

9.2.  Informative References

   [RFC8340]  Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
              BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
              <https://www.rfc-editor.org/info/rfc8340>.

   [RFC8343]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
              <https://www.rfc-editor.org/info/rfc8343>.

   [RFC8525]  Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
              and R. Wilton, "YANG Library", RFC 8525,
              DOI 10.17487/RFC8525, March 2019,
              <https://www.rfc-editor.org/info/rfc8525>.

Appendix A.  Vendor-Specific Subservice Augmentation: "example-service-
             assurance-device-acme" YANG Module

A.1.  Tree View

   The following tree diagram [RFC8340] provides an overview of the
   "example-service-assurance-device-acme" module.

   module: example-service-assurance-device-acme

     augment /sain:subservices/sain:subservice/sain:parameter:
       +--rw parameters
          +--rw device                     string
          +--rw acme-specific-parameter    string

   A complete tree view of the base module with all augmenting modules
   presented in this document is available in Appendix B.3.

A.2.  Concepts

   Under some circumstances, vendor-specific subservice types might be
   required.  As an example of this vendor-specific implementation, this
   section shows how to augment the "ietf-service-assurance-device"
   module to add custom support for the device subservice specific to
   the Acme Corporation.  The specific version adds a new parameter
   named "acme-specific-parameter".  It's an implementation choice to
   either derive a new specific identity from the "subservice-base"
   identity defined in the "ietf-service-assurance" module or to augment
   the parameters from the "ietf-service-assurance-device" module; here,
   we choose to create a new identity.

A.3.  YANG Module

   module example-service-assurance-device-acme {
     yang-version 1.1;
     namespace "urn:example:example-service-assurance-device-acme";
     prefix example-device-acme;

     import ietf-service-assurance {
       prefix sain;
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }
     import ietf-service-assurance-device {
       prefix sain-device;
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
        WG List:  <mailto:opsawg@ietf.org>
        Author:   Benoit Claise  <mailto:benoit.claise@huawei.com>
        Author:   Jean Quilbeuf   <mailto:jean.quilbeuf@huawei.com>";
     description
       "This example module extends the ietf-service-assurance-device
        module to add specific support for devices of the Acme
        Corporation. ";

     revision 2023-07-11 {
       description
         "Initial revision.";
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     identity device-acme-type {
       base sain-device:device-type;
       description
         "Network device is healthy.";
     }

     augment "/sain:subservices/sain:subservice/sain:parameter" {
       when "derived-from-or-self(sain:type, 'device-acme-type')";
       description
         "Augments the parameter choice from the ietf-service-assurance
          module with a case specific to the device-acme subservice.";
       container parameters {
         description
           "Parameters for the device-acme subservice type.";
         leaf device {
           type string;
           mandatory true;
           description
             "The device to monitor.";
         }
         leaf acme-specific-parameter {
           type string;
           mandatory true;
           description
             "The Acme-Corporation-specific parameter.";
         }
       }
     }
   }

Appendix B.  Further Augmentations: IP Connectivity and IS-IS
             Subservices

   In this section, we provide two additional YANG modules to completely
   cover the example in Figure 2 from Section 3.1 of [RFC9417].  The two
   missing subservice types are IP connectivity and the Intermediate
   System to Intermediate System (IS-IS) routing protocol.  These
   modules are presented as examples; some future work is needed to
   propose a more complete version.

B.1.  IP Connectivity Module Tree View

   That subservice represents the unicast connectivity between two IP
   addresses located on two different devices.  Such a subservice could
   report symptoms such as "No route found".  The following tree diagram
   [RFC8340] provides an overview of the "example-service-assurance-ip-
   connectivity" module.

   module: example-service-assurance-ip-connectivity

     augment /sain:subservices/sain:subservice/sain:parameter:
       +--rw parameters
          +--rw device1     string
          +--rw address1    inet:ip-address
          +--rw device2     string
          +--rw address2    inet:ip-address

   To specify the connectivity that we are interested in, we specify two
   IP addresses and two devices.  The subservice assures that the
   connectivity between IP address 1 on device 1 and IP address 2 on
   device 2 is healthy.

B.2.  IS-IS Module Tree View

   The following tree diagram [RFC8340] provides an overview of the
   "example-service-assurance-is-is" module.

   module: example-service-assurance-is-is

     augment /sain:subservices/sain:subservice/sain:parameter:
       +--rw parameters
          +--rw instance-name    string

   The parameter of this subservice is the name of the IS-IS instance to
   assure.

B.3.  Global Tree View

   The following tree diagram [RFC8340] provides an overview of the
   "ietf-service-assurance", "ietf-service-assurance-device", "example-
   service-assurance-device-acme", "example-service-assurance-ip-
   connectivity", and "example-service-assurance-is-is" modules.

   module: ietf-service-assurance
     +--ro assurance-graph-last-change    yang:date-and-time
     +--rw subservices
     |  +--rw subservice* [type id]
     |     +--rw type                                        identityref
     |     +--rw id                                          string
     |     +--ro last-change?
     |     |       yang:date-and-time
     |     +--ro label?                                      string
     |     +--rw under-maintenance!
     |     |  +--rw contact    string
     |     +--rw (parameter)
     |     |  +--:(service-instance-parameter)
     |     |  |  +--rw service-instance-parameter
     |     |  |     +--rw service          string
     |     |  |     +--rw instance-name    string
     |     |  +--:(example-ip-connectivity:parameters)
     |     |  |  +--rw example-ip-connectivity:parameters
     |     |  |     +--rw example-ip-connectivity:device1     string
     |     |  |     +--rw example-ip-connectivity:address1
     |     |  |     |       inet:ip-address
     |     |  |     +--rw example-ip-connectivity:device2     string
     |     |  |     +--rw example-ip-connectivity:address2
     |     |  |             inet:ip-address
     |     |  +--:(example-is-is:parameters)
     |     |  |  +--rw example-is-is:parameters
     |     |  |     +--rw example-is-is:instance-name    string
     |     |  +--:(sain-device:parameters)
     |     |  |  +--rw sain-device:parameters
     |     |  |     +--rw sain-device:device    string
     |     |  +--:(example-device-acme:parameters)
     |     |  |  +--rw example-device-acme:parameters
     |     |  |     +--rw example-device-acme:device
     |     |  |     |       string
     |     |  |     +--rw example-device-acme:acme-specific-parameter
     |     |  |             string
     |     |  +--:(sain-interface:parameters)
     |     |     +--rw sain-interface:parameters
     |     |        +--rw sain-interface:device       string
     |     |        +--rw sain-interface:interface    string
     |     +--ro health-score                                int8
     |     +--ro symptoms-history-start?
     |     |       yang:date-and-time
     |     +--ro symptoms
     |     |  +--ro symptom* [start-date-time agent-id symptom-id]
     |     |     +--ro symptom-id             leafref
     |     |     +--ro agent-id               -> /agents/agent/id
     |     |     +--ro health-score-weight?   uint8
     |     |     +--ro start-date-time        yang:date-and-time
     |     |     +--ro stop-date-time?        yang:date-and-time
     |     +--rw dependencies
     |        +--rw dependency* [type id]
     |           +--rw type
     |           |       -> /subservices/subservice/type
     |           +--rw id                 leafref
     |           +--rw dependency-type?   identityref
     +--ro agents
     |  +--ro agent* [id]
     |     +--ro id          string
     |     +--ro symptoms* [id]
     |        +--ro id             string
     |        +--ro description    string
     +--ro assured-services
        +--ro assured-service* [service]
           +--ro service      leafref
           +--ro instances* [name]
              +--ro name           leafref
              +--ro subservices* [type id]
                 +--ro type    -> /subservices/subservice/type
                 +--ro id      leafref

B.4.  IP Connectivity YANG Module

   module example-service-assurance-ip-connectivity {
     yang-version 1.1;
     namespace "urn:example:example-service-assurance-ip-connectivity";
     prefix example-ip-connectivity;

     import ietf-inet-types {
       prefix inet;
       reference
         "RFC 6991: Common YANG Data Types";
     }
     import ietf-service-assurance {
       prefix sain;
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
        WG List:  <mailto:opsawg@ietf.org>
        Author:   Benoit Claise  <mailto:benoit.claise@huawei.com>
        Author:   Jean Quilbeuf   <mailto:jean.quilbeuf@huawei.com>";
     description
       "This example module augments the ietf-service-assurance module
        to add support for the subservice ip-connectivity.

        It checks whether the IP connectivity between two IP addresses
        belonging to two network devices is healthy.";

     revision 2023-07-11 {
       description
         "Initial version.";
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     identity ip-connectivity-type {
       base sain:subservice-base;
       description
         "Checks connectivity between two IP addresses.";
     }

     augment "/sain:subservices/sain:subservice/sain:parameter" {
       when "derived-from-or-self(sain:type, 'ip-connectivity-type')";
       description
         "Augments the parameter choice from the ietf-service-assurance
          module with a case specific to the ip-connectivity
          subservice.";
       container parameters {
         description
           "Parameters for the ip-connectivity subservice type.";
         leaf device1 {
           type string;
           mandatory true;
           description
             "Device at the first end of the connection.";
         }
         leaf address1 {
           type inet:ip-address;
           mandatory true;
           description
             "Address at the first end of the connection.";
         }
         leaf device2 {
           type string;
           mandatory true;
           description
             "Device at the second end of the connection.";
         }
         leaf address2 {
           type inet:ip-address;
           mandatory true;
           description
             "Address at the second end of the connection.";
         }
       }
     }
   }

B.5.  IS-IS YANG Module

   module example-service-assurance-is-is {
     yang-version 1.1;
     namespace "urn:example:example-service-assurance-is-is";
     prefix example-is-is;

     import ietf-service-assurance {
       prefix sain;
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
        WG List:  <mailto:opsawg@ietf.org>
        Author:   Benoit Claise  <mailto:benoit.claise@huawei.com>
        Author:   Jean Quilbeuf  <mailto:jean.quilbeuf@huawei.com>";
     description
       "This example module augments the ietf-service-assurance module
        to add support for the subservice is-is.

        It checks whether an IS-IS instance is healthy.";

     revision 2023-07-11 {
       description
         "Initial version.";
       reference
         "RFC 9418: YANG Modules for Service Assurance";
     }

     identity is-is-type {
       base sain:subservice-base;
       description
         "Health of IS-IS routing protocol.";
     }

     augment "/sain:subservices/sain:subservice/sain:parameter" {
       when "derived-from-or-self(sain:type, 'is-is-type')";
       description
         "Augments the parameter choice from the ietf-service-assurance
          module with a case specific to the is-is subservice.";
       container parameters {
         description
           "Parameters for the is-is subservice type.";
         leaf instance-name {
           type string;
           mandatory true;
           description
             "The instance to monitor.";
         }
       }
     }
   }

Appendix C.  Example of a YANG Instance

   This section contains an example of a YANG instance that conforms to
   the YANG modules.  The validity of this data instance has been
   checked using yangson <https://yangson.labs.nic.cz/>.  Yangson
   requires a YANG library [RFC8525] to define the complete model
   against which the data instance must be validated.  In Appendix D, we
   provide the JSON library file named "ietf-service-assurance-
   library.json", which we used for validation.

   Below, we provide the contents of the file
   "example_configuration_instance.json", which contains the
   configuration data that models Figure 2 from Section 3.1 of
   [RFC9417].  The instance can be validated with yangson by using the
   invocation "yangson -v example_configuration_instance.json ietf-
   service-assurance-library.json", assuming all the files (YANG and
   JSON) defined in this document reside in the current folder.

   {
     "ietf-service-assurance:subservices": {
       "subservice": [
         {
           "type": "service-instance-type",
           "id": "simple-tunnel/example",
           "service-instance-parameter": {
             "service": "simple-tunnel",
             "instance-name": "example"
           },
           "dependencies": {
             "dependency": [
               {
                 "type":
                   "ietf-service-assurance-interface:interface-type",
                 "id": "interface/peer1/tunnel0",
                 "dependency-type": "impacting"
               },
               {
                 "type":
                   "ietf-service-assurance-interface:interface-type",
                 "id": "interface/peer2/tunnel9",
                 "dependency-type": "impacting"
               },
               {
                 "type":
       "example-service-assurance-ip-connectivity:ip-connectivity-type",
                 "id":
                   "connectivity/peer1/2001:db8::1/peer2/2001:db8::2",
                 "dependency-type": "impacting"
               }
             ]
           }
         },
         {
           "type":
       "example-service-assurance-ip-connectivity:ip-connectivity-type",
           "id": "connectivity/peer1/2001:db8::1/peer2/2001:db8::2",
           "example-service-assurance-ip-connectivity:parameters": {
             "device1": "Peer1",
             "address1": "2001:db8::1",
             "device2": "Peer2",
             "address2": "2001:db8::2"
           },
           "dependencies": {
             "dependency": [
               {
                 "type":
                   "ietf-service-assurance-interface:interface-type",
                 "id": "interface/peer1/physical0",
                 "dependency-type": "impacting"
               },
               {
                 "type":
                   "ietf-service-assurance-interface:interface-type",
                 "id": "interface/peer2/physical5",
                 "dependency-type": "impacting"
               },
               {
                 "type": "example-service-assurance-is-is:is-is-type",
                 "id": "is-is/instance1",
                 "dependency-type": "impacting"
               }
             ]
           }
         },
         {
           "type": "example-service-assurance-is-is:is-is-type",
           "id": "is-is/instance1",
           "example-service-assurance-is-is:parameters": {
             "instance-name": "instance1"
           }
         },
         {
           "type": "ietf-service-assurance-interface:interface-type",
           "id": "interface/peer1/tunnel0",
           "ietf-service-assurance-interface:parameters": {
             "device": "Peer1",
             "interface": "tunnel0"
           },
           "dependencies": {
             "dependency": [
               {
                 "type":
                   "ietf-service-assurance-interface:interface-type",
                 "id": "interface/peer1/physical0",
                 "dependency-type": "impacting"
               }
             ]
           }
         },
         {
           "type": "ietf-service-assurance-interface:interface-type",
           "id": "interface/peer1/physical0",
           "ietf-service-assurance-interface:parameters": {
             "device": "Peer1",
             "interface": "physical0"
           },
           "dependencies": {
             "dependency": [
               {
                 "type": "ietf-service-assurance-device:device-type",
                 "id": "interface/peer1",
                 "dependency-type": "impacting"
               }
             ]
           }
         },
         {
           "type": "ietf-service-assurance-device:device-type",
           "id": "interface/peer1",
           "ietf-service-assurance-device:parameters": {
             "device": "Peer1"
           }
         },
         {
           "type": "ietf-service-assurance-interface:interface-type",
           "id": "interface/peer2/tunnel9",
           "ietf-service-assurance-interface:parameters": {
             "device": "Peer2",
             "interface": "tunnel9"
           },
           "dependencies": {
             "dependency": [
               {
                 "type":
                   "ietf-service-assurance-interface:interface-type",
                 "id": "interface/peer2/physical5",
                 "dependency-type": "impacting"
               }
             ]
           }
         },
         {
           "type": "ietf-service-assurance-interface:interface-type",
           "id": "interface/peer2/physical5",
           "ietf-service-assurance-interface:parameters": {
             "device": "Peer2",
             "interface": "physical5"
           },
           "dependencies": {
             "dependency": [
               {
                 "type": "ietf-service-assurance-device:device-type",
                 "id": "interface/peer2",
                 "dependency-type": "impacting"
               }
             ]
           }
         },
         {
           "type": "ietf-service-assurance-device:device-type",
           "id": "interface/peer2",
           "ietf-service-assurance-device:parameters": {
             "device": "Peer2"
           }
         }
       ]
     }
   }

Appendix D.  YANG Library for Service Assurance

   This section provides the JSON encoding of the YANG library [RFC8525]
   that lists all modules defined in this document and their
   dependencies.  This library can be used to validate data instances
   using yangson, as explained in the previous section.

   {
     "ietf-yang-library:modules-state": {
       "module-set-id": "ietf-service-assurance@2023-07-11",
       "module": [
         {
           "name": "ietf-service-assurance",
           "namespace":
             "urn:ietf:params:xml:ns:yang:ietf-service-assurance",
           "revision": "2023-07-11",
           "conformance-type": "implement"
         },
         {
           "name": "ietf-service-assurance-device",
           "namespace":
            "urn:ietf:params:xml:ns:yang:ietf-service-assurance-device",
           "revision": "2023-07-11",
           "conformance-type": "implement"
         },
         {
           "name": "ietf-service-assurance-interface",
           "namespace":
         "urn:ietf:params:xml:ns:yang:ietf-service-assurance-interface",
           "revision": "2023-07-11",
           "conformance-type": "implement"
         },
         {
           "name": "example-service-assurance-device-acme",
           "namespace":
             "urn:example:example-service-assurance-device-acme",
           "revision": "2023-07-11",
           "conformance-type": "implement"
         },
         {
           "name": "example-service-assurance-is-is",
           "namespace": "urn:example:example-service-assurance-is-is",
           "revision": "2023-07-11",
           "conformance-type": "implement"
         },
         {
           "name": "example-service-assurance-ip-connectivity",
           "namespace":
             "urn:example:example-service-assurance-ip-connectivity",
           "revision": "2023-07-11",
           "conformance-type": "implement"
         },
         {
           "name": "ietf-yang-types",
           "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types",
           "revision": "2013-07-05",
           "conformance-type": "import"
         },
         {
           "name": "ietf-inet-types",
           "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types",
           "revision": "2013-07-05",
           "conformance-type": "import"
         }
       ]
     }
   }

Acknowledgements

   The authors would like to thank Jan Lindblad for his help during the
   design of these YANG modules.  The authors would like to thank
   Stephane Litkowski, Charles Eckel, Mohamed Boucadair, Tom Petch,
   Dhruv Dhody, and Rob Wilton for their reviews.

Authors' Addresses

   Benoit Claise
   Huawei
   Email: benoit.claise@huawei.com


   Jean Quilbeuf
   Huawei
   Email: jean.quilbeuf@huawei.com


   Paolo Lucente
   NTT
   Siriusdreef 70-72
   2132 Hoofddorp
   Netherlands
   Email: paolo@ntt.net


   Paolo Fasano
   TIM S.p.A
   via G. Reiss Romoli, 274
   10148 Torino
   Italy
   Email: paolo2.fasano@telecomitalia.it


   Thangavelu Arumugam
   Consultant
   Milpitas, California
   United States of America
   Email: thangavelu@yahoo.com