doc: Add RFC documents

1 files changed, 1998 insertions, 0 deletions

diff --git a/doc/rfc/rfc9418.txt b/doc/rfc/rfc9418.txt
new file mode 100644
index 0000000..5669675
--- /dev/null
+++ b/doc/rfc/rfc9418.txt
@@ -0,0 +1,1998 @@
+
+
+
+
+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