module bbf-availability {

    yang-version 1.1;

    namespace
      "urn:bbf:yang:bbf-availability";

    prefix bbf-avail;

    organization
      "Broadband Forum <https://www.broadband-forum.org>
     Common YANG Work Area";

    contact
      "Comments or questions about this Broadband Forum YANG module
     should be directed to <mailto:help@broadband-forum.org>.

     Editor:      Nick Hancock, Adtran

     Editor:      Ludwig Pauwels, Nokia

     PS Leader:   Joey Boyd, Adtran

     WA Director: Joey Boyd, Adtran

     WA Director: Sven Ooghe, Nokia";

    description
      "This module contains a collection of YANG definitions for
     supporting the Broadband Forum requirements on the general
     availability of specific resources as applicable to access
     network equipment. As such, this module is specific to access
     network equipment (e.g., BBF-specified Access Nodes and FTTdp
     DPUs).

     Copyright (c) 2017-2023, Broadband Forum

     Redistribution and use in source and binary forms, with or
     without modification, are permitted provided that the following
     conditions are met:

     1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

     2. Redistributions in binary form must reproduce the above
        copyright notice, this list of conditions and the following
        disclaimer in the documentation and/or other materials
        provided with the distribution.

     3. Neither the name of the copyright holder nor the names of its
        contributors may be used to endorse or promote products
        derived from this software without specific prior written
        permission.

     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
     CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES,
     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
     CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

     The above license is used as a license under copyright only.
     Please reference the Forum IPR Policy for patent licensing terms
     <https://www.broadband-forum.org/ipr-policy>.

     Any moral rights which are necessary to exercise under the above
     license grant are also deemed granted under this license.

     This version of this YANG module is part of TR-383a7; see
     the TR itself for full legal notices.";

    revision "2023-12-15" {
      description
        "Amendment 7.
       * Approval Date:    2023-12-15.
       * Publication Date: 2023-12-15.";
      reference
        "TR-383a7: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-7.pdf>";

    }

    revision "2022-03-01" {
      description
        "Amendment 5.
       * Approval Date:    2022-03-01.
       * Publication Date: 2022-03-01.";
      reference
        "TR-383a5: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-5.pdf>";

    }

    revision "2020-10-13" {
      description
        "Amendment 3.
       * Approval Date:    2020-10-13.
       * Publication Date: 2020-10-13.";
      reference
        "TR-383a3: Common YANG Modules
        	  <https://www.broadband-forum.org/technical/download/
        		   TR-383_Amendment-3.pdf>";

    }

    revision "2018-07-13" {
      description
        "Amendment 1.
       * Approval Date:    2018-06-04.
       * Publication Date: see revision date above.";
      reference
        "TR-383: Common YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-383_Amendment-1.pdf>";

    }


    feature availability {
      description
        "Indicates support for retrieving availability of resources.";
    }

    identity issue-tag {
      description
        "The base identity for issue tags to enable categorizing types
       issues which affect the availability of resources.";
    }

    identity hardware-fault {
      base bbf-avail:issue-tag;
      description
        "The resource has an hardware fault that prevents it from
       operating.";
    }

    identity peer-not-reachable {
      base bbf-avail:issue-tag;
      description
        "A peer resource for which the resource inter-operates is not
       reachable.";
    }

    identity feature-not-supported {
      base bbf-avail:issue-tag;
      description
        "A feature which the resource needs to provide the required
       service is not supported on the device which has to provide
       the service.";
    }

    identity invalid-configuration {
      base bbf-avail:issue-tag;
      description
        "The current configuration is not valid for some reason.";
    }

    identity unknown {
      base bbf-avail:issue-tag;
      description
        "The type of issue which is affecting the availability of
       resources is unknown.";
    }

    typedef availability-status {
      type bits {
        bit in-test {
          position 0;
          description
            "The resource is undergoing a test procedure.";
        }
        bit failed {
          position 1;
          description
            "The resource has an internal fault that prevents it
           from operating.";
        }
        bit offline {
          position 2;
          description
            "The resource requires a routine operation to be performed
           to place it online and make it available for use. The
           operation may be manual or automatic, or both.";
        }
        bit off-duty {
          position 3;
          description
            "The resource has been made inactive by a control process in
           accordance with a predetermined time schedule. Under normal
           conditions the control process can be expected to
           reactivate the resource at some scheduled time.";
        }
        bit dependency {
          position 4;
          description
            "The resource cannot operate because some other resource on
           which it depends is unavailable.";
        }
        bit degraded {
          position 5;
          description
            "The service available from the resource is degraded in some
           respect, such as in speed or operating capacity. Failure of
           a test or an unacceptable performance measurement has
           established that some or all services are not functional or
           are degraded, for example, due to the presence of a defect
           or an inappropriate configuration. However, the resource
           remains available for service, either because some services
           are satisfactory or because degraded service is preferable
           to no service at all. Further information indicating, for
           example, which services are not functional or which
           configuration is inappropriate and the nature of the
           degradation, may be found in the container 'issues'.";
        }
        bit not-installed {
          position 6;
          description
            "The resource or resources represented by the data nodes
           are not present or are incomplete.";
        }
        bit log-full {
          position 7;
          description
            "This indicates a log full condition.";
        }
      }
      description
        "A set of availability status conditions. An empty set of bits
       implies that none of the status conditions are present, i.e.,
       the entity is available.";
      reference
        "ITU-T X.731 clause 8.1.2.3.";

    }

    typedef unspecified-availability-status {
      type enumeration {
        enum "unspecified" {
          value 0;
          description
            "The resource is impaired, but the X.731 availability status
           condition(s) cannot be determined or X.731 availability
           condition(s) are not supported by the device. This permits
           devices that do not support X.731 availability status
           condition(s) to nevertheless make use of the availability
           status parameters.";
        }
      }
      description
        "Defines an alternative definition of availability where a
       device may not support specification of the availability status
       according to that defined by ITU-T X.731.";
    }

    typedef resource {
      type union {
        type instance-identifier;
        type string;
      }
      description
        "This identifies a resource, such as an interface, which is a
       cause of one or more availability status conditions.

       It should be as fine-grained as possible both to guide the
       operator. If the instrumentation can detect a broken config,
       this should be identified as the resource.

       If the resource is modeled in YANG, this type will be an
       instance-identifier. If the resource is anything else, for
       example a distinguished name, this type will be a string.";
    }

    grouping availability-parameters {
      description
        "Defines the availability of entities.";
      leaf availability-status {
        type union {
          type availability-status;
          type unspecified-availability-status;
        }
        mandatory true;
        description
          "The set of availability status conditions currently defining
         the availability status of the resource. An empty set of bits
         implies that none of the status conditions are present, i.e.,
         the entity is available.";
        reference
          "ITU-T X.731 clause 8.1.2.3.";

      }

      container issues {
        description
          "Issues that have been identified by the instrumentation that
         are affecting the availability status.";
        list issue {
          key "tag code";
          description
            "An issue affecting the availability status.";
          leaf tag {
            type identityref {
              base issue-tag;
            }
            description
              "The specific issue tag indicating the type of issue
             encountered, if any.";
          }

          leaf code {
            type uint16;
            must
              "not(../tag='bbf-avail:unknown') or
                (../tag='bbf-avail:unknown' and .=0)";
            description
              "A well-known code uniquely identifying the specific
             condition, if any. This code may be vendor-specific.";
          }

          leaf message {
            type string;
            description
              "A string suitable for human display that describes the
             condition causing the issue.";
          }

          leaf-list root-cause {
            type resource;
            description
              "Identifies a resource, such as an interface, if any,
             which can be identified as a possible root cause of
             the issue.";
          }
        }  // list issue
      }  // container issues
    }  // grouping availability-parameters

    grouping availability {
      description
        "Defines the availability of entities.";
      container availability {
        if-feature bbf-avail:availability;
        presence
          "If present, this container indicates supports for retrieving
         the availability of the entity for which it is used.";
        config false;
        description
          "Operational status defining the availability of an entity.";
        uses availability-parameters;
      }  // container availability
    }  // grouping availability
  }  // module bbf-availability