Skip to main content

A Common YANG Data Model for Scheduling
draft-ietf-netmod-schedule-yang-00

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Active".
Authors Qiufang Ma , Qin Wu , Mohamed Boucadair , Daniel King
Last updated 2024-04-16
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state I-D Exists
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-netmod-schedule-yang-00
OPSAWG                                                        Q. Ma, Ed.
Internet-Draft                                                     Q. Wu
Intended status: Standards Track                                  Huawei
Expires: 18 October 2024                               M. Boucadair, Ed.
                                                                  Orange
                                                                 D. King
                                                    Lancaster University
                                                           16 April 2024

                A Common YANG Data Model for Scheduling
                   draft-ietf-netmod-schedule-yang-00

Abstract

   This document defines a common schedule YANG module which is designed
   to be applicable for scheduling information such as event, policy,
   services, or resources based on date and time.  For the sake of
   better modularity, the module includes basic, intermediate, and
   advanced versions of recurrence related groupings.

Status of This Memo

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

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

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

   This Internet-Draft will expire on 18 October 2024.

Copyright Notice

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

Ma, et al.               Expires 18 October 2024                [Page 1]
Internet-Draft            Common Schedule YANG                April 2024

   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  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Editorial Note (To be removed by RFC Editor)  . . . . . .   3
   2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   3
   3.  Module Overview . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  The "generic-schedule-params" Grouping  . . . . . . . . .   4
     3.2.  The "period-of-time" Grouping . . . . . . . . . . . . . .   5
     3.3.  The "recurrence" Grouping . . . . . . . . . . . . . . . .   6
     3.4.  The "recurrence-with-date-times" Grouping . . . . . . . .   8
     3.5.  The "icalendar-recurrence" Grouping . . . . . . . . . . .   9
     3.6.  The "schedule-status" Grouping  . . . . . . . . . . . . .  11
   4.  Features and Augmentations  . . . . . . . . . . . . . . . . .  12
   5.  Note and Restrictions . . . . . . . . . . . . . . . . . . . .  13
   6.  The "ietf-schedule" YANG Module . . . . . . . . . . . . . . .  13
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  28
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  28
     8.1.  The "IETF XML" Registry . . . . . . . . . . . . . . . . .  29
     8.2.  The "YANG Module Names" Registry  . . . . . . . . . . . .  29
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  29
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  29
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  30
   Appendix A.  Examples of Format Representation  . . . . . . . . .  32
     A.1.  The "period-of-time" Grouping . . . . . . . . . . . . . .  32
     A.2.  The "recurrence" Grouping . . . . . . . . . . . . . . . .  32
     A.3.  The "recurrence-with-date-times" Grouping . . . . . . . .  33
     A.4.  The "icalendar-recurrence" Grouping . . . . . . . . . . .  34
   Appendix B.  Examples of Using/Extending the "ietf-schedule"
           Module  . . . . . . . . . . . . . . . . . . . . . . . . .  35
     B.1.  Example: Schedule Tasks to Execute Based on a Recurrence
           Rule  . . . . . . . . . . . . . . . . . . . . . . . . . .  35
     B.2.  Example: Schedule Network Properties to Change Based on
           Date and Time . . . . . . . . . . . . . . . . . . . . . .  38
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  41
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  41

1.  Introduction

   Several specifications include a provision for scheduling.  Examples
   of such specifications are (but not limited to)
   [I-D.ietf-opsawg-ucl-acl],
   [I-D.contreras-opsawg-scheduling-oam-tests], and
   [I-D.united-tvr-schedule-yang].  Both [I-D.ietf-opsawg-ucl-acl] and
   [I-D.contreras-opsawg-scheduling-oam-tests] use the "ietf-schedule"

Ma, et al.               Expires 18 October 2024                [Page 2]
Internet-Draft            Common Schedule YANG                April 2024

   module initially specified in [I-D.ietf-opsawg-ucl-acl].

   Given that the applicability of the "ietf-schedule" module is more
   general than scheduled policy and OAM tests, this document defines
   "ietf-schedule" as a common schedule YANG module.  The module
   includes a set of reusable groupings which are designed to be
   applicable for scheduling information such as event, policy, services
   or resources based on date and time.

   Examples to illustrate the use of the common groupings are provided
   in Appendix A.  Also, sample modules to exemplify how future modules
   can use the extensibility provisions in "ietf-schedule" are provided
   in Appendix B.

1.1.  Editorial Note (To be removed by RFC Editor)

   Note to the RFC Editor: This section is to be removed prior to
   publication.

   This document contains placeholder values that need to be replaced
   with finalized values at the time of publication.  This note
   summarizes all of the substitutions that are needed.  No other RFC
   Editor instructions are specified elsewhere in this document.

   Please apply the following replacements:

   *  XXXX --> the assigned RFC number for this draft

   *  YYYY --> the assigned RFC number for [I-D.ietf-netmod-rfc6991-bis]

   *  2023-01-19 --> the actual date of the publication of this document

2.  Conventions and Definitions

   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 meanings of the symbols in tree diagrams are defined in
   [RFC8340].

   Also, this document uses the YANG terminology defined in Section 3 of
   [RFC7950].

Ma, et al.               Expires 18 October 2024                [Page 3]
Internet-Draft            Common Schedule YANG                April 2024

3.  Module Overview

   The "ietf-schedule" module (Section 6) defines the following
   groupings:

   *  "generic-schedule-params" (Section 3.1)

   *  "period-of-time" (Section 3.2)

   *  "recurrence" (Section 3.3)

   *  "recurrence-with-date-times" (Section 3.4)

   *  "icalendar-recurrence" (Section 3.5)

   *  "schedule-status" (Section 3.6)

   Figure 1 provides an overview of the tree structure [RFC8340] of the
   "ietf-schedule" module in terms of its groupings.

   module: ietf-schedule

     grouping generic-schedule-params:
       ...
     grouping period-of-time:
       ...
     grouping recurrence:
       ...
     grouping recurrence-with-date-times:
       ...
     grouping icalendar-recurrence:
       ...
     grouping schedule-status:
       ...

                 Figure 1: Overall Schedule Tree Structure

   Each of these groupings is presented in the following subsections.
   Examples are provided in Appendix A.

3.1.  The "generic-schedule-params" Grouping

   The "generic-schedule-params" grouping (Figure 2) specifies a set of
   configuration parameters that are used by a system for validating
   requested schedules.  These parameters apply to all schedules on a
   system and are meant to provide guards against stale configuration,
   too short schedule requests that would prevent validation by admins
   of some critical systems, etc.

Ma, et al.               Expires 18 October 2024                [Page 4]
Internet-Draft            Common Schedule YANG                April 2024

   module: ietf-schedule

     grouping generic-schedule-params:
       +-- time-zone-identifier?   sys:timezone-name
       +-- validity?               yang:date-and-time
       +-- max-allowed-start?      yang:date-and-time
       +-- min-allowed-start?      yang:date-and-time
       +-- max-allowed-end?        yang:date-and-time
       +-- discard-action?         enumeration
     grouping period-of-time:
       ...
     grouping recurrence:
       ...
     grouping recurrence-with-date-times:
       ...
     grouping icalendar-recurrence:
       ...
     grouping schedule-status:
       ...

          Figure 2: Generic Schedule Configuration Tree Structure

3.2.  The "period-of-time" Grouping

   The "period-of-time" grouping (Figure 3) represents a time period
   using either a start ("period-start") and end date and time ("period-
   end"), or a start ("period-start") and a positive time duration
   ("duration").  For the first format, the start of the period MUST be
   before the end of the period.

Ma, et al.               Expires 18 October 2024                [Page 5]
Internet-Draft            Common Schedule YANG                April 2024

   module: ietf-schedule

     grouping generic-schedule-params:
       ...
     grouping period-of-time:
       +-- period-start?           yang:date-and-time
       +-- time-zone-identifier?   sys:timezone-name
       +-- (period-type)?
          +--:(explicit)
          |  +-- period-end?       yang:date-and-time
          +--:(duration)
             +-- duration?         duration
     grouping recurrence:
       ...
     grouping recurrence-with-date-times:
       ...
     grouping icalendar-recurrence:
       ...
     grouping schedule-status:
       ...

              Figure 3: Period of Time Grouping Tree Structure

3.3.  The "recurrence" Grouping

   The "recurrence" grouping (Figure 4) specifies a simple recurrence
   rule, the definition conforms to part of the "recurrence rule"
   properties in Section 3.3.10 of [RFC5545].

Ma, et al.               Expires 18 October 2024                [Page 6]
Internet-Draft            Common Schedule YANG                April 2024

   module: ietf-schedule

     grouping generic-schedule-params:
       ...
     grouping period-of-time:
       ...
     grouping recurrence:
       +-- recurrence-first
       |  +-- date-time-start?        union
       |  +-- time-zone-identifier?   sys:timezone-name
       |  +-- duration?               duration
       +-- frequency?          identityref
       +-- interval?           uint32
       +-- (recurrence-bound)?
          +--:(until)
          |  +-- until?        union
          +--:(count)
             +-- count?        uint32
     grouping recurrence-with-date-times:
       ...
     grouping icalendar-recurrence:
       ...
     grouping schedule-status:
       ...

                Figure 4: Recurrence Grouping Tree Structure

   The "recurrence-first" container defines the first instance in the
   recurrence set.  It also determines the start time and duration (if
   specified) of subsequent recurrence instances.  If the "date-time-
   start" node is specified as a date-no-zone value type with no
   duration specified, the recurrence's duration is taken to be one day.

   The frequency ("frequency") identifies the type of recurrence rule.
   For example, a "daily" frequency value specifies repeating events
   based on an interval of a day or more.

   The interval represents at which intervals the recurrence rule
   repeats.  For example, within a daily recurrence rule, an interval
   value of "8" means every eight days.

   The repetition can be scoped by a specified end time or by a count of
   occurrences, indicated by the "recurrence-bound" choice.  The "date-
   time-start" value always counts as the first occurrence.

Ma, et al.               Expires 18 October 2024                [Page 7]
Internet-Draft            Common Schedule YANG                April 2024

3.4.  The "recurrence-with-date-times" Grouping

   The "recurrence-with-date-times" grouping (Figure 5) uses the
   "recurrence" grouping (Section 3.3) and adds a "date-times-choice"
   statement to define an aggregate set of repeating occurrences.

   module: ietf-schedule

     grouping generic-schedule-params:
       ...
     grouping period-of-time:
       ...
     grouping recurrence:
       ...
     grouping recurrence-with-date-times:
       +-- recurrence-first
       |  +-- date-time-start?        union
       |  +-- time-zone-identifier?   sys:timezone-name
       |  +-- duration?               duration
       +-- frequency?                identityref
       +-- interval?                 uint32
       +-- (recurrence-bound)?
       |  +--:(until)
       |  |  +-- until?              union
       |  +--:(count)
       |     +-- count?              uint32
       +-- (date-times-choice)?
          +--:(date-time)
          |  +-- date-times*         yang:date-and-time
          +--:(date)
          |  +-- dates*              yang:date-no-zone
          +--:(period-timeticks)
          |  +-- period-timeticks* [period-start]
          |     +-- period-start?   yang:timeticks
          |     +-- period-end?     yang:timeticks
          +--:(period)
             +-- period* [period-start]
                +-- period-start?           yang:date-and-time
                +-- time-zone-identifier?   sys:timezone-name
                +-- (period-type)?
                   +--:(explicit)
                   |  +-- period-end?       yang:date-and-time
                   +--:(duration)
                      +-- duration?         duration
     grouping icalendar-recurrence:
       ...
     grouping schedule-status:
       ...

Ma, et al.               Expires 18 October 2024                [Page 8]
Internet-Draft            Common Schedule YANG                April 2024

        Figure 5: Recurrence with Date Times Grouping Tree Structure

   The recurrence instances are defined by the union of occurrences
   defined by both date-times and recurrence rule.  When duplicate
   instances are generated, only one recurrence is considered.

   Date-times definition inside "recurrence-with-date-times" grouping
   refers to but does not fully comply with Section 3.8.5.2 of
   [RFC5545].  A timeticks type based period is added.

3.5.  The "icalendar-recurrence" Grouping

   The "icalendar-recurrence" grouping (Figure 6) uses the "recurrence-
   with-date-times" grouping (Section 3.4) and add more data nodes to
   enrich the definition of recurrence.  The structure of the
   "icalendar-recurrence" grouping conforms to the definition of
   recurrence component defined in Section 3.8.5 of [RFC5545].

   module: ietf-schedule

     grouping generic-schedule-params:
       ...
     grouping period-of-time:
       ...
     grouping recurrence:
       ...
     grouping recurrence-with-date-times:
       ...
     grouping icalendar-recurrence:
       +-- recurrence-first
       |  +-- date-time-start?        union
       |  +-- time-zone-identifier?   sys:timezone-name
       |  +-- duration?               duration
       +-- frequency?                identityref
       +-- interval?                 uint32
       +-- (recurrence-bound)?
       |  +--:(until)
       |  |  +-- until?              union
       |  +--:(count)
       |     +-- count?              uint32
       +-- (date-times-choice)?
       |  +--:(date-time)
       |  |  +-- date-times*         yang:date-and-time
       |  +--:(date)
       |  |  +-- dates*              yang:date-no-zone
       |  +--:(period-timeticks)
       |  |  +-- period-timeticks* [period-start]
       |  |     +-- period-start?   yang:timeticks

Ma, et al.               Expires 18 October 2024                [Page 9]
Internet-Draft            Common Schedule YANG                April 2024

       |  |     +-- period-end?     yang:timeticks
       |  +--:(period)
       |     +-- period* [period-start]
       |        +-- period-start?           yang:date-and-time
       |        +-- time-zone-identifier?   sys:timezone-name
       |        +-- (period-type)?
       |           +--:(explicit)
       |           |  +-- period-end?       yang:date-and-time
       |           +--:(duration)
       |              +-- duration?         duration
       +-- bysecond*                 uint32
       +-- byminute*                 uint32
       +-- byhour*                   uint32
       +-- byday* [weekday]
       |  +-- direction*   int32
       |  +-- weekday?     schedule:weekday
       +-- bymonthday*               int32
       +-- byyearday*                int32
       +-- byyearweek*               int32
       +-- byyearmonth*              uint32
       +-- bysetpos*                 int32
       +-- workweek-start?           schedule:weekday
       +-- exception-dates*          union
     grouping schedule-status:
       ...

           Figure 6: iCalendar Recurrence Grouping Tree Structure

   An array of the "bysecond" (or "byminut", "byhour") specifies a list
   of seconds within a minute (or minutes within an hour, hours of the
   day).

   The parameter "byday" specifies a list of days of the week, with an
   optional direction which indicates the nth occurrence of a specific
   day within the "monthly" or "yearly" frequency.  For example, within
   a "monthly" rule, the "weekday" with a value of "monday" and the
   "direction" with a value of "-1" represents the last Monday of the
   month.

   An array of the "bymonthday" (or byyearday", "byyearweek", or
   "byyearmonth") specifies a list of days of the month (or days of the
   year, weeks of the year, or months of the year).

Ma, et al.               Expires 18 October 2024               [Page 10]
Internet-Draft            Common Schedule YANG                April 2024

   The "bysetpos" conveys a list of values that corresponds to the nth
   occurrence within the set of recurrence instances to be specified.
   For example, in a "monthly" recurrence rule, the "byday" data node
   specifies every Monday of the week, the "bysetpos" with value of "-1"
   represents the last Monday of the month.  Not setting the "bysetpos"
   data node represents every Monday of the month.

   The "workweek-start" data node specifies the day on which the week
   starts.  This is significant when a "weekly" recurrence rule has an
   interval greater than 1, and a "byday" data node is specified.  This
   is also significant when in a "yearly" rule and a "byyearweek" is
   specified.  The default value is "monday".

   The "exception-dates" data node specifies a list of exceptions for
   recurrence.  The final recurrence set is generated by gathering all
   of the date and time values generated by any of the specified
   recurrence rule and date-times, and then excluding any start date and
   time values specified by "exception-dates" parameter.

3.6.  The "schedule-status" Grouping

   The "schedule-status" grouping (Figure 7) defines common parameters
   for scheduling management/status exposure.

   module: ietf-schedule

     grouping generic-schedule-params:
       ...
     grouping period-of-time:
       ...
     grouping recurrence:
       ...
     grouping recurrence-with-date-times:
       ...
     grouping icalendar-recurrence:
       ...
     grouping schedule-status:
       +-- schedule-id?           string
       +-- state?                 identityref
       +-- version?               uint16
       +--ro schedule-type?         identityref
       +--ro last-update?           yang:date-and-time
       +--ro counter?               uint32
       +--ro last-occurrence?       yang:date-and-time
       +--ro upcoming-occurrence?   yang:date-and-time

             Figure 7: Schedule Status Grouping Tree Structure

Ma, et al.               Expires 18 October 2024               [Page 11]
Internet-Draft            Common Schedule YANG                April 2024

   The "schedule-id" parameter is useful to uniquely identify a schedule
   in a network device or controller if multiple scheduling contexts
   exists.

   The "state" parameter is defined to configure/expose the scheduling
   state, depending on the use of the grouping.  The "identityref" type
   is used for this parameter to allow extensibility in future modules.
   For example, a "conflict" state is valid in scheduling contexts where
   multiple systems struggle for the scheduling of the same property.
   The conflict may be induced by, e.g., multiple entities managing the
   schedules for the same target component.

   The "version" parameter is used to track the current schedule version
   information.  The version can be bumped by the entity who create the
   schedule.  The "last-update" parameter identifies when the schedule
   was last modified.  In some contexts, this parameter can be used to
   track the configuration of a given schedule.  In such cases, the
   "version" may not be used.

   The "schedule-type" parameter identifies the type of the current
   schedule.  The "counter", "last-occurrence", and "upcoming-
   occurrence" data nodes are only avaliable when the "schedule-type" is
   "recurrence".

   The current grouping captures common parameters that is applicable to
   typical scheduling contexts known so far.  Future modules can define
   other useful parameters as needed.  For example, in a scheduling
   context with multiple system sources to feed the schedules, the
   "source" and "precedence" parameters may be needed to reflect how
   schedules from different sources should be prioritised.

4.  Features and Augmentations

   The "ietf-schedule" data model defines the recurrence related
   groupings using a modular approach.  Basic, intermediate, and
   advanced representation of recurrence groupings are defined, with
   each reusing the previous one and adding more parameters.  To allow
   for different options, two features are defined in the data model:

   *  'basic-recurrence-supported'

   *  'icalendar-recurrence-supported'

   Appendix B.1 provides an example about how that could be used.
   Implementations may support a basic recurrence rule or an advanced
   one as needed, by declaring different features.  Whether only one or
   both features are supported is implementation specific and depend on
   specific scheduling context.

Ma, et al.               Expires 18 October 2024               [Page 12]
Internet-Draft            Common Schedule YANG                April 2024

   These groupings can also be augmented to support specific needs.  As
   an example, Appendix B.2 demonstrates how additional parameters can
   be added to comply with specifc schedule needs.

5.  Note and Restrictions

   There are some restrictions that need to be followed when using
   groupings defined in "ietf-schedule" yang module:

   *  The instant in time represented by "period-start" MUST be before
      the "period-end" for "period-of-time" grouping

   *  The combination of the day, month, and year represented for date
      and time value MUST be valid.  See Section 5.7 of [RFC3339] for
      the maxinum day number based on the month and year.

   *  The second MUST have the value "60" at the end of months in which
      a leap second occurs for date and time value

   *  Care must be taken when defining recurrence occurring very often
      and frequent that can be an additional source of attacks by
      keeping the system permanently busy with the management of
      scheduling

   *  Schedules received with a starting time in the past with respect
      to current time SHOULD be ignored

6.  The "ietf-schedule" YANG Module

   This module imports types defined in [I-D.ietf-netmod-rfc6991-bis].

   <CODE BEGINS> file "ietf-schedule@2023-01-19.yang"
   module ietf-schedule {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-schedule";
     prefix schedule;

     import ietf-yang-types {
       prefix yang;
       revision-date 2023-01-23;
       reference
         "RFC YYYY: Common YANG Data Types";
     }

     import ietf-system {
       prefix sys;
       reference
         "RFC 7317: A YANG Data Model for System Management";

Ma, et al.               Expires 18 October 2024               [Page 13]
Internet-Draft            Common Schedule YANG                April 2024

     }

     organization
       "IETF OPSAWG Working Group";
     contact
       "WG Web: <https://datatracker.ietf.org/wg/opsawg/>
        WG List: <mailto:opsawg@ietf.org>

        Editor:   Qiufang Ma
                  <mailto:maqiufang1@huawei.com
        Author:   Qin Wu
                  <mailto:bill.wu@huawei.com>
        Editor:   Mohamed Boucadair
                  <mailto:mohamed.boucadair@orange.com>
        Author:   Daniel King
                  <mailto:d.king@lancaster.ac.uk>";
     description
       "This YANG module defines two groupings for iCalendar (Internet
        Calendaring and Scheduling Core Object Specification) data
        types: period of time and recurrence rule, for representing and
        exchanging calendaring and scheduling information. The YANG
        module complies with Sections 3.3.9 and 3.3.10 of RFC 5545.

        Copyright (c) 2024 IETF Trust and the persons identified
        as authors of the code. All rights reserved.

        Redistribution and use in source and binary forms, with
        or without modification, is permitted pursuant to, and
        subject to the license terms contained in, the 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 XXXX
        (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
        itself for full legal notices.

        The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
        NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
        'MAY', and 'OPTIONAL' in this document are to be interpreted as
        described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
        they appear in all capitals, as shown here.";

     revision 2023-01-19 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: A YANG Data Model for Scheduling";

Ma, et al.               Expires 18 October 2024               [Page 14]
Internet-Draft            Common Schedule YANG                April 2024

     }

     feature basic-recurrence-supported {
       description
         "Indicates that the server supports configuring a basic
          scheduled recurrence.";
     }

     feature icalendar-recurrence-supported {
       description
         "Indicates that the server supports configuring a comprehensive
          scheduled icalendar recurrence";
       reference
         "RFC 5545: Internet Calendaring and Scheduling Core Object
                    Specification (iCalendar),
                    Sections 3.3.10 and 3.8.5";
     }

     typedef weekday {
       type enumeration {
         enum sunday {
           value 0;
           description
             "Sunday of the week.";
         }
         enum monday {
           value 1;
           description
             "Monday of the week.";
         }
         enum tuesday {
           value 2;
           description
             "Tuesday of the week.";
         }
         enum wednesday {
           value 3;
           description
             "Wednesday of the week.";
         }
         enum thursday {
           value 4;
           description
             "Thursday of the week.";
         }
         enum friday {
           value 5;
           description

Ma, et al.               Expires 18 October 2024               [Page 15]
Internet-Draft            Common Schedule YANG                April 2024

             "Friday of the week.";
         }
         enum saturday {
           value 6;
           description
             "Saturday of the week.";
         }
       }
       description
         "Seven days of the week.";
     }

     typedef duration {
       type string {
         pattern '((\+)?|\-)P((([0-9]+)D)?(T(0[0-9]|1[0-9]|2[0-3])'
               + ':[0-5][0-9]:[0-5][0-9]))|P([0-9]+)W';
       }
       description
         "Duration of the time. The format can represent nominal
          durations (weeks designated by 'W' and days designated by 'D')
          and accurate durations (hours:minutes:seconds follows the
          designator 'T').

          Note that this value type doesn't support the 'Y' and 'M'
          designators to specify durations in terms of years and months.

          Negative durations are typically used to schedule an alarm to
          trigger before an associated time.";
       reference
         "RFC 5545: Internet Calendaring and Scheduling Core Object
                    Specification (iCalendar), Sections 3.3.6 and
                    3.8.6.3";
     }

     identity frequency-type {
       description
         "Base identity for frequency type.";
     }
     identity secondly {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of
          a second or more.";
     }
     identity minutely {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of

Ma, et al.               Expires 18 October 2024               [Page 16]
Internet-Draft            Common Schedule YANG                April 2024

          a minute or more.";
     }
     identity hourly {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of
          an hour or more.";
     }
     identity daily {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of
          a day or more.";
     }
     identity weekly {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of
          a week or more.";
     }
     identity monthly {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of
          a month or more.";
     }
     identity yearly {
       base frequency-type;
       description
         "Identity for a repeating event based on an interval of
          a year or more.";
     }
     identity schedule-type {
       description
         "Base identity for schedule type.";
     }
     identity period {
       base schedule-type;
       description
         "Identity for a period based schedule.";
     }

     identity recurrence {
       base schedule-type;
       description
         "Identity for a recurrence based schedule.";
     }
     identity schedule-state {

Ma, et al.               Expires 18 October 2024               [Page 17]
Internet-Draft            Common Schedule YANG                April 2024

       description
         "Base identity for schedule state.";
     }
     identity enabled {
       description
         "Identity for the recurrence with enabled state.";
     }
     identity disabled {
       description
         "Identity for the recurrence with disabled state.";
     }
     identity out-of-date {
       description
         "Identity for the recurrence with out-of-date state.";
     }

     grouping generic-schedule-params {
       description
         "Incldues a set of generic configuration parameters that are
          followed by the entity that supports schedules.

          These parameters apply to all schedules.

           Such parameters are used as guards to prevent, e.g., stale
           configuration.";
       leaf time-zone-identifier {
         type sys:timezone-name;
         description
           "Indicates the identifier for the time zone in a time zone
            database.";
       }
       leaf validity {
         type yang:date-and-time;
         description
           "Specifies the date and time after which a schedule will
            be considered as invalid. This paratemer takes precedence
            over similar attributes that are provided at the schedule
            instance itself.";
       }
       leaf max-allowed-start {
         type yang:date-and-time;
         description
           "Specifies the date and time after which a requested schedule
            instance cannot be accepted by the entity. Specifically,
            a requested schedule will be rejected if the first occurence
            of that new schedule exceeds 'max-allowed-start'.";
       }
       leaf min-allowed-start {

Ma, et al.               Expires 18 October 2024               [Page 18]
Internet-Draft            Common Schedule YANG                April 2024

         type yang:date-and-time;
         description
           "Specifies the date and time before which a requested
            schedule instance cannot be accepted by the entity.
            Specifically, a requested schedule will be rejected if the
            first occurence of that new schedule is to be scheduled
            before 'min-allowed-start'.";
       }
       leaf max-allowed-end {
         type yang:date-and-time;
         description
           "A requested schedule will be rejected if the last
            occurence of that schedule or its duratioon exceed
            'max-allowed-end'.";
       }
       leaf discard-action {
         type enumeration {
           enum warning {
             description
               "A warning message is generated when a schedule is
                discarded when enforcing the guards in this grouping
                or it is received out-of-date.";
           }
           enum silently-discard {
             description
              "Discards silently a schedule when it is invalid because
               it is not consistent with the guards in this grouping or
               it is received out-of-date.";
           }
         }
         description
           "Specifies the behavior when a schedule is discarded.";
       }
     }

     grouping period-of-time {
       description
         "This grouping is defined for period of time property.";
       reference
         "RFC 5545: Internet Calendaring and Scheduling Core Object
                    Specification (iCalendar), Section 3.3.9";
       leaf period-start {
         type yang:date-and-time;
         description
           "Period start time.";
       }
       leaf time-zone-identifier {
         type sys:timezone-name;

Ma, et al.               Expires 18 October 2024               [Page 19]
Internet-Draft            Common Schedule YANG                April 2024

         description
           "Indicates the identifier for the time zone in a time zone
            database. This parameter MUST be specified if 'period-start'
            value is neither reported in the format of UTC nor time zone
            offset to UTC.";
       }
       choice period-type {
         description
           "Indicates the type of the time period. Two types are
             supported.";
         case explicit {
           description
             "A period of time is identified by its start and its end.
              'period-start' indicates the period start.";
           leaf period-end {
             type yang:date-and-time;
             description
               "Period end time. The start MUST be before the end. If a
                local time without time zone offset to UTC time is
                specified, it MUST use the same time zone reference as
                'period-start' parameter. If 'period-start' also uses a
                local time without time zone offset to UTC, it MUST use
                the time zone as specified by the
                'time-zone-identifier' parameter.";
           }
         }
         case duration {
           description
             "A period of time is defined by a start and a
              positive duration of time.";
           leaf duration {
             type duration {
               pattern 'P((([0-9]+)D)?(T(0[0-9]|1[0-9]|2[0-3])'
                     + ':[0-5][0-9]:[0-5][0-9]))|P([0-9]+)W';
             }
             description
               "A positive duration of the time. This value is
                equivalent to the format of duration type except that
                the value cannot be negative.";
           }
         }
       }
     }

     grouping recurrence {
       description
         "A simple definition of recurrence.";
       container recurrence-first {

Ma, et al.               Expires 18 October 2024               [Page 20]
Internet-Draft            Common Schedule YANG                April 2024

         description
           "Specifies the first instance of the recurrence.";
         leaf date-time-start {
           type union {
             type yang:date-no-zone;
             type yang:date-and-time;
           }
           description
             "Defines the first instance in the recurrence set. If it is
              specified as a date-no-zone value type with no duration
              specified, the recurrence's duration is taken to be one
              day.";
           reference
             "RFC 5545: Internet Calendaring and Scheduling Core Object
                        Specification (iCalendar), Section 3.3.10";
         }
         leaf time-zone-identifier {
           type sys:timezone-name;
           description
             "Indicates the identifier for the time zone in a time zone
              database. This parameter MUST be specified if 'start'
              value is neither reported in the format of UTC nor time
              zone offset to UTC.";
         }
         leaf duration {
           type duration;
           description
             "When specified, it refers to the duration of
              the first occurrence. The exact duration also applies to
              all the recurrence instance.";
         }
       }
       leaf frequency {
         type identityref {
           base frequency-type;
         }
         description
           "This parameter is defined to identify the frequency type of
            the recurrence rule.";
       }
       leaf interval {
         type uint32;
         description
           "A positive integer representing at which intervals the
            recurrence rule repeats. For example, within a 'daily'
            recurrence rule, a value of '8' means every eight days.";
       }
       choice recurrence-bound {

Ma, et al.               Expires 18 October 2024               [Page 21]
Internet-Draft            Common Schedule YANG                April 2024

         description
           "Modes to bound the recurrence rule. If no choice is
            indicated, the recurrence rule is considered to repeat
            forever.";
         case until {
           description
             "This case defines a way that bounds the recurrence
              rule in an inclusive manner.";
           leaf until {
             type union {
               type yang:date-no-zone;
               type yang:date-and-time;
             }
             description
               "This parameter specifies a date-no-zone or
                date-time value to bounds the recurrence. If the value
                specified by this parameter is synchronized with the
                specified recurrence, it becomes the last instance of
                the recurrence. The value MUST have the same value type
                as the value type of 'start' parameter.";
           }
         }
         case count {
           description
             "This case defines the number of occurrences at which
              to range-bound the recurrence.";
           leaf count {
             type uint32;
             description
               "The positive number of occurrences at which to
                range-bound the recurrence.";
           }
         }
       }
     }

     grouping recurrence-with-date-times {
       description
         "This grouping defines an aggregate set of repeating
          occurrences. The recurrence instances are defined by
          the union of occurrences defined by both the
          'recurrence' and 'date-times'. Duplicate instances
          are ignored.";
       uses recurrence;
       choice date-times-choice {
         description
           "Specify a list of occurrences which complement the
            recurrence set defined by 'recurrence' grouping. If

Ma, et al.               Expires 18 October 2024               [Page 22]
Internet-Draft            Common Schedule YANG                April 2024

            it is specified as a period value, the duration of
            the recurrence instance will be the one specified
            by it, and not the duration defined inside the
            recurrence-first parameter.";
         case date-time {
           description
             "Specify a list of occurrences with date-and-time
              values.";
             leaf-list date-times {
               type yang:date-and-time;
               description
                 "Specifies a set of date-and-time values of
                  occurrences.";
             }
         }
         case date {
           description
             "Specifies a list of occurrences with date-no-zone
              values.";
             leaf-list dates {
               type yang:date-no-zone;
               description
                 "Specifies a set of date-no-zone values of
                  occurrences.";
             }
         }
         case period-timeticks {
           description
             "Specifies a list of occurrences with period span of
              timeticks format.";
             list period-timeticks {
               key "period-start";
               description
                 "A list of period with timeticks formats.";
               leaf period-start {
                 type yang:timeticks;
                 must
                 "(not(derived-from(../../frequency,"
                +"'schedule:secondly')) or (current() < 100)) and "
                +"(not(derived-from(../../frequency,"
                +"'schedule:minutely')) or (current() < 6000)) and "
                +"(not(derived-from(../../frequency,'schedule:hourly'))"
                +" or (current() < 360000)) and "
                +"(not(derived-from(../../frequency,'schedule:daily'))"
                +" or (current() < 8640000)) and "
                +"(not(derived-from(../../frequency,'schedule:weekly'))"
                +" or (current() < 60480000)) and "
                +"(not(derived-from(../../frequency,"

Ma, et al.               Expires 18 October 2024               [Page 23]
Internet-Draft            Common Schedule YANG                April 2024

                +"'schedule:monthly')) or (current() < 267840000)) and "
                +"(not(derived-from(../../frequency,'schedule:yearly'))"
                +" or (current() < 3162240000))" {
                   error-message
                     "The period-start must not exceed the frequency
                      interval.";
                 }
                 description
                   "Start time of the scheduled value within one
                    recurrence.";
               }
               leaf period-end {
                 type yang:timeticks;
                 description
                   "End time of the scheduled value within one
                    recurrence.";
               }
             }
         }
         case period {
           description
             "Specifies a list of occurrences with period span
              of date-and -time format.";
           list period {
             key "period-start";
             description
               "A list of period with date-and-time formats.";
             uses period-of-time;
           }
         }
       }
     }

     grouping icalendar-recurrence {
       description
         "This grouping is defined to identify properties
          that contain a recurrence rule.";
       reference
         "RFC 5545: Internet Calendaring and Scheduling
                    Core Object Specification (iCalendar),
                    Section 3.8.5";

       uses recurrence-with-date-times;
       leaf-list bysecond {
         type uint32 {
           range "0..60";
         }
         description

Ma, et al.               Expires 18 October 2024               [Page 24]
Internet-Draft            Common Schedule YANG                April 2024

           "A list of seconds within a minute.";
       }
       leaf-list byminute {
         type uint32 {
           range "0..59";
         }
         description
           "A list of minutes within an hour.";
       }
       leaf-list byhour {
         type uint32 {
           range "0..23";
         }
         description
           "Specifies a list of hours of the day.";
       }
       list byday {
         key "weekday";
         description
           "Specifies a list of days of the week.";
         leaf-list direction {
           when "derived-from(../../frequency, 'schedule:monthly') or "
             +  "(derived-from(../../frequency, 'schedule:yearly') "
             +  " and not(../../byyearweek))";
           type int32 {
             range "-53..-1|1..53";
           }
           description
             "When specified, it indicates the nth occurrence of a
              specific day within the monthly or yearly recurrence
              rule.
              For example, within a monthly rule, +1 monday represents
              the first monday within the month, whereas -1 monday
              represents the last monday of the month.";
         }
         leaf weekday {
           type schedule:weekday;
           description
             "Corredponds to seven days of the week.";
         }
       }

       leaf-list bymonthday {
         type int32 {
           range "-31..-1|1..31";
         }
         description
           "Specifies a list of days of the month.";

Ma, et al.               Expires 18 October 2024               [Page 25]
Internet-Draft            Common Schedule YANG                April 2024

       }
       leaf-list byyearday {
         type int32 {
           range "-366..-1|1..366";
         }
         description
           "Specifies a list of days of the year.";
       }
       leaf-list byyearweek {
         when "derived-from(../frequency, 'schedule:yearly')";
         type int32 {
           range "-53..-1|1..53";
         }
         description
           "Specifies a list of weeks of the year.";
       }
       leaf-list byyearmonth {
         type uint32 {
           range "1..12";
         }
         description
           "Specifies a list of months of the year.";
       }
       leaf-list bysetpos {
         type int32 {
           range "-366..-1|1..366";
         }
         description
           "Specifies a list of values that corresponds to the nth
            occurrence within the set of recurrence instances
            specified by the rule. It must only be used in conjunction
            with another by the rule part.";
       }
       leaf workweek-start {
         type schedule:weekday;
         default "monday";
         description
           "Specifies the day on which the workweek starts.";
       }
       leaf-list exception-dates {
         type union {
           type yang:date-no-zone;
           type yang:date-and-time;
         }
         description
           "Defines a list of exceptions for recurrence.";
       }
     }

Ma, et al.               Expires 18 October 2024               [Page 26]
Internet-Draft            Common Schedule YANG                April 2024

     grouping schedule-status {
       description
         "This grouping is defined to identify common properties of
          scheduling status.";
       leaf schedule-id {
         type string;
         description
           "The schedule identifier that globally identifies a
            schedule in a device, controller, network, etc.
            The unicity scope depends on the implementation.";
       }
       leaf state {
         type identityref {
           base schedule-state;
         }
         description
           "The current state of the schedule.";
       }
       leaf version {
         type uint16;
         description
           "The version number of the schedule.";
       }
       leaf schedule-type {
         type identityref {
           base schedule-type;
         }
         config false;
         description
           "The schedule type.";
       }
       leaf last-update {
         type yang:date-and-time;
         config false;
         description
           "The timestamp that the schedule is last updated.";
       }
       leaf counter {
         when "derived-from-or-self(../schedule-type, "
            + "'schedule:recurrence')";
         type uint32;
         config false;
         description
           "The counter of occurrences since the schedule was enabled.
            The count wraps around when it reaches the maximum value.";
       }
       leaf last-occurrence {
         when "derived-from-or-self(../schedule-type, "

Ma, et al.               Expires 18 October 2024               [Page 27]
Internet-Draft            Common Schedule YANG                April 2024

            + "'schedule:recurrence')";
         type yang:date-and-time;
         config false;
         description
           "The timestamp of last occurrence.";
       }
       leaf upcoming-occurrence {
         when "derived-from-or-self(../schedule-type, "
            + "'schedule:recurrence')"
            + "and derived-from-or-self(../state, 'schedule:enabled')";
         type yang:date-and-time;
         config false;
         description
           "The timestamp of next occurrence.";
       }
     }
   }
   <CODE ENDS>

7.  Security Considerations

   This section uses the template described in Section 3.7 of
   [I-D.ietf-netmod-rfc8407bis].

   The "ietf-schedule" YANG module specified in this document defines
   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.

   The "ietf-schedule" module defines a set of types and groupings.
   These nodes are intended to be reused by other YANG modules.  The
   module by itself does not expose any data nodes that are writable,
   data nodes that contain read-only state, or RPCs.  As such, there are
   no additional security issues related to the "ietf- schedule" module
   that need to be considered.

8.  IANA Considerations

Ma, et al.               Expires 18 October 2024               [Page 28]
Internet-Draft            Common Schedule YANG                April 2024

8.1.  The "IETF XML" Registry

   This document registers the following URI in the "IETF XML Registry"
   [RFC3688].

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

8.2.  The "YANG Module Names" Registry

   This document registers the following YANG module in the "YANG Module
   Names" registry [RFC6020].

           name:               ietf-schedule
           namespace:          urn:ietf:params:xml:ns:yang:ietf-schedule
           prefix:             schedule
           maintained by IANA: N
           reference:          RFC XXXX

9.  References

9.1.  Normative References

   [I-D.ietf-netmod-rfc6991-bis]
              Schönwälder, J., "Common YANG Data Types", Work in
              Progress, Internet-Draft, draft-ietf-netmod-rfc6991-bis-
              15, 23 January 2023,
              <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
              rfc6991-bis-15>.

   [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>.

   [RFC5545]  Desruisseaux, B., Ed., "Internet Calendaring and
              Scheduling Core Object Specification (iCalendar)",
              RFC 5545, DOI 10.17487/RFC5545, September 2009,
              <https://www.rfc-editor.org/info/rfc5545>.

Ma, et al.               Expires 18 October 2024               [Page 29]
Internet-Draft            Common Schedule YANG                April 2024

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [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>.

   [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>.

   [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>.

9.2.  Informative References

   [I-D.contreras-opsawg-scheduling-oam-tests]
              Contreras, L. M. and V. Lopez, "A YANG Data Model for
              Network Diagnosis by scheduling sequences of OAM tests",
              Work in Progress, Internet-Draft, draft-contreras-opsawg-
              scheduling-oam-tests-01, 10 July 2023,
              <https://datatracker.ietf.org/doc/html/draft-contreras-
              opsawg-scheduling-oam-tests-01>.

   [I-D.ietf-netmod-eca-policy]
              Wu, Q., Bryskin, I., Birkholz, H., Liu, X., and B. Claise,
              "A YANG Data model for ECA Policy Management", Work in

Ma, et al.               Expires 18 October 2024               [Page 30]
Internet-Draft            Common Schedule YANG                April 2024

              Progress, Internet-Draft, draft-ietf-netmod-eca-policy-01,
              19 February 2021, <https://datatracker.ietf.org/doc/html/
              draft-ietf-netmod-eca-policy-01>.

   [I-D.ietf-netmod-rfc8407bis]
              Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for
              Authors and Reviewers of Documents Containing YANG Data
              Models", Work in Progress, Internet-Draft, draft-ietf-
              netmod-rfc8407bis-10, 15 April 2024,
              <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
              rfc8407bis-10>.

   [I-D.ietf-opsawg-ucl-acl]
              Ma, Q., Wu, Q., Boucadair, M., and D. King, "A YANG Data
              Model and RADIUS Extension for Policy-based Network Access
              Control", Work in Progress, Internet-Draft, draft-ietf-
              opsawg-ucl-acl-03, 2 February 2024,
              <https://datatracker.ietf.org/doc/html/draft-ietf-opsawg-
              ucl-acl-03>.

   [I-D.ietf-tvr-use-cases]
              Birrane, E. J., Kuhn, N., Qu, Y., Taylor, R., and L.
              Zhang, "TVR (Time-Variant Routing) Use Cases", Work in
              Progress, Internet-Draft, draft-ietf-tvr-use-cases-09, 29
              February 2024, <https://datatracker.ietf.org/doc/html/
              draft-ietf-tvr-use-cases-09>.

   [I-D.united-tvr-schedule-yang]
              Qu, Y., Lindem, A., Kinzie, E., Fedyk, D., and M.
              Blanchet, "YANG Data Model for Scheduled Attributes", Work
              in Progress, Internet-Draft, draft-united-tvr-schedule-
              yang-01, 3 March 2024,
              <https://datatracker.ietf.org/doc/html/draft-united-tvr-
              schedule-yang-01>.

   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
              <https://www.rfc-editor.org/info/rfc3339>.

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

   [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>.

Ma, et al.               Expires 18 October 2024               [Page 31]
Internet-Draft            Common Schedule YANG                April 2024

Appendix A.  Examples of Format Representation

   This section provides some examples to illustrate the use of the
   period and recurrence formats defined as YANG groupings.  Note that
   "grouping" does not define any data nodes in the schema tree, the
   examples illustrated are just for the ease of understanding.  Only
   the message body is provided with JSON used for encoding [RFC7951].

A.1.  The "period-of-time" Grouping

   The example of a period that starts at 08:00:00 UTC, on January 1,
   2025 and ends at 18:00:00 UTC on December 31, 2027 is encoded as
   shown in Figure 8.

   {
     "period-start": "2025-01-01T08:00:00Z",
     "period-end": "2027-12-01T18:00:00Z"
   }

                    Figure 8: Simple Start/End Schedule

   An example of a period that starts at 08:00:00 UTC, on January 1,
   2025 and lasts 15 days and 5 hours and 20 minutes is encoded as shown
   in Figure 9.

   {
     "period-start": "2025-01-01T08:00:00Z",
     "duration": "P15DT05:20:00"
   }

                  Figure 9: Simple Schedule with Duration

   An example of a period that starts at 2:00 A.M. in Los Angeles on
   November 19, 2025 and lasts 20 weeks is depicted in Figure 10.

   {
     "period-start": "2025-11-19T02:00:00",
     "time-zone-identifier": "America/Los_Angeles",
     "duration": "P20W"
   }

            Figure 10: Simple Schedule with Time Zone Indication

A.2.  The "recurrence" Grouping

   Figure 11 indicates a recurrence of every 2 days for 10 occurrences,
   starting at 3 p.m. on December 1, 2025 in the Eastern United States
   time zone:

Ma, et al.               Expires 18 October 2024               [Page 32]
Internet-Draft            Common Schedule YANG                April 2024

   {
     "recurrence-first": {
       "date-time-start": "2025-11-01T15:00:00",
       "time-zone-identifier": "America/New_York"
     },
     "frequency": "ietf-schedule:daily",
     "interval": 2,
     "count": 10
   }

                 Figure 11: Simple Schedule with Recurrence

   Figure 12 illustrates an example of an anniversary that will occur
   annually, from 1997-11-25, until 2050-11-25:

   {
     "recurrence-first": {
       "date-time-start": "1979-11-25"
     },
     "frequency": "ietf-schedule:yearly",
     "until": "2050-11-25"
   }

          Figure 12: Simple Schedule with Recurrence and End Date

A.3.  The "recurrence-with-date-times" Grouping

   Figure 13 indicates a recurrence that occurs every 2 hours from 9:00
   AM to 5:00 PM, and 6PM UTC time on 2025-12-01:

   {
     "recurrence-first": {
       "date-time-start": "2025-12-01T09:00:00Z"
     },
     "frequency": "ietf-schedule:hourly",
     "interval": 2,
     "until": "2025-12-01T17:00:00Z",
     "date-times": ["2025-12-01T18:00:00Z"]
   }

              Figure 13: Example of Recurrence With Date Times

   Figure 14 indicates a recurrence that occurs every 30 minutes and
   last for 15 minutes from 9:00 AM to 5:00 PM, and extra two
   occurrences at 6:00 PM and 6:30 PM with each lasting for 20 minutes
   on 2025-12-01:

Ma, et al.               Expires 18 October 2024               [Page 33]
Internet-Draft            Common Schedule YANG                April 2024

   {
     "recurrence-first": {
       "date-time-start": "2025-12-01T09:00:00Z",
       "duration": "PT00:15:00"
     },
     "frequency": "ietf-schedule:minutely",
     "interval": 30,
     "until": "2025-12-01T17:00:00Z",
     "period": [
       {
         "period-start": "2025-12-01T18:00:00Z",
         "duration": "PT00:20:00"
       },
       {
         "period-start": "2025-12-01T18:30:00Z",
         "duration": "PT00:20:00"
       }
      ]
   }

             Figure 14: Example of Advanced Recurrence Schedule

A.4.  The "icalendar-recurrence" Grouping

   Figure 15 indicates 10 occurrences that occur at 8:00 AM (EST), every
   last Saturday of the month starting in January 2024:

   {
     "recurrence-first": {
       "date-time-start": "2024-01-27T08:00:00",
       "time-zone-identifier": "America/New_York"
     },
     "frequency": "ietf-schedule:monthly",
     "count": 10,
     "byday": [
       {
         "direction": [-1],
         "weekday": "saturday"
       }
     ]
   }

                   Figure 15: Simple iCalendar Recurrence

   Figure 16 is an example of a recurrence that occurs on the last
   workday of the month until December 25, 2024, from January 1, 2024:

Ma, et al.               Expires 18 October 2024               [Page 34]
Internet-Draft            Common Schedule YANG                April 2024

   {
     "recurrence-first": {
     "date-time-start": "2024-01-01"
     },
     "frequency": "ietf-schedule:monthly",
     "until": "2024-12-25",
     "byday": [
       { "weekday": "monday"},
       { "weekday": "tuesday"},
       { "weekday": "wednesday"},
       { "weekday": "thursday"},
       { "weekday": "friday"}
     ],
     "bysetpos": [-1]
   }

            Figure 16: Example of Advanced iCalendar Recurrence

   Figure 17 indicates a recurrence that occur every 20 minutes from
   9:00 AM to 4:40 PM (UTC), with the occurrence starting at 10:20 AM
   being excluded on 2025-12-01:

   {
     "recurrence-first": {
       "date-time-start": "2025-12-01T09:00:00Z"
     },
     "until": "2025-12-01T16:40:00Z",
     "frequency": "ietf-schedule:minutely",
     "byminute": [0, 20, 40],
     "byhour": [9, 10, 11, 12, 13, 14, 15, 16],
     "exception-dates": ["2025-12-01T10:20:00Z"]
   }

    Figure 17: Example of Advanced iCalendar Recurrence with Exceptions

Appendix B.  Examples of Using/Extending the "ietf-schedule" Module

   This non-normative section shows two examples for how the "ietf-
   schedule" module can be used or extended for scheduled events or
   attributes based on date and time.

B.1.  Example: Schedule Tasks to Execute Based on a Recurrence Rule

   Scheduled tasks can be used to execute specific actions based on
   certain recurrence rules (e.g., every Friday at 8:00 AM).  The
   following example module which "uses" the "icalendar-recurrence"
   grouping from "ietf-schedule" module shows how a scheduled task could
   be defined with different features used for options.

Ma, et al.               Expires 18 October 2024               [Page 35]
Internet-Draft            Common Schedule YANG                April 2024

   module example-scheduled-backup {
     yang-version 1.1;
     namespace "http://example.com/example-scheduled-backup";
     prefix "ex-scback";

     import ietf-inet-types {
       prefix "inet";
     }

     import ietf-schedule {
       prefix "schedule";
     }

     organization
       "Example, Inc.";

     contact
       "Support at example.com";

     description
       "Example of a module defining an scheduled based backup
        operation.";

     revision "2023-01-19" {
       description
         "Initial Version.";
       reference
         "RFC XXXX: A YANG Data Model for Scheduling.";
       }

     container scheduled-backup-tasks {
       description
         "A container for backing up all current running configuration
          on the device.";
       list tasks {
         key "task-id";
         description
           "The list of backing up tasks on this device.";
         leaf task-id {
           type string;
           description
             "The task identifier that uniquely identifies a scheduled
              backup task.";
         }
         choice local-or-remote {
           description
             "Specifies whether the configuration to be backed up is
              local or remote.";

Ma, et al.               Expires 18 October 2024               [Page 36]
Internet-Draft            Common Schedule YANG                April 2024

           case local {
             description
               "Configuration parameters for backing up of local
                devices.";
             leaf local {
               type empty;
               description
                 "The parameter specifies the configuration to be
                  backed up is on the local device.";
             }
           }
           case remote {
             description
               "Configuration parameters for backing up of remote
                devices.";
             leaf remote {
               type inet:domain-name;
               description
                 "The parameter specifies the remote device domain
                  name.";
             }
           }
         }

         container basic-recurrence-schedules {
           if-feature schedule:basic-recurrence-supported;
           description
             "Basic recurrence schedule specification, only applies when
              schedule:basic-recurrence-supported feaure is supported.";
           leaf schedule-id {
             type string;
             description
               "The schedule identifier for this recurrence rule.";
           }
           uses schedule:recurrence;
          }

         container icalendar-recurrence-schedules {
           if-feature schedule:icalendar-recurrence-supported;
           description
             "Basic recurrence schedule specification, only applies when
              schedule:icalendar-recurrence-supported feaure is
              supported.";
           leaf schedule-id {
             type string;
             description
               "The schedule identifier for this recurrence rule.";
           }

Ma, et al.               Expires 18 October 2024               [Page 37]
Internet-Draft            Common Schedule YANG                April 2024

           uses schedule:icalendar-recurrence;
         }
       }

       list schedule-set {
         key "schedule-id";
         description
           "The list of schedule status for the backup tasks.";
         uses schedule:schedule-status;
       }
     }
   }

B.2.  Example: Schedule Network Properties to Change Based on Date and
      Time

   Network properties may change over a specific period of time or based
   on a recurrence rule, e.g., [I-D.ietf-tvr-use-cases].  The following
   example module which augments the "recurrence-with-date-times"
   grouping from "ietf-schedule" module shows how a scheduled based
   attribute could be defined.

   module example-scheduled-link-bandwidth {
     yang-version 1.1;
     namespace "http://example.com/example-scheduled-link-bandwidth";
     prefix "ex-scattr";

     import ietf-network {
       prefix "nw";
       reference
         "RFC 8345: A YANG Data Model for Network Topologies";
     }

     import ietf-schedule {
       prefix "schedule";
       reference
         "RFC XXXX: A YANG Data Model for Scheduling";
     }

     organization
       "Example, Inc.";

     contact
       "Support at example.com";

     description
       "Example of a module defining a scheduled link bandwidth.";

Ma, et al.               Expires 18 October 2024               [Page 38]
Internet-Draft            Common Schedule YANG                April 2024

     revision "2023-01-19" {
       description
         "Initial Version.";
       reference
         "RFC XXXX: A YANG Data Model for Scheduling.";
       }

     grouping link-bandwidth-grouping {
       description
         "Grouping of the link bandwidth definition.";
       leaf scheduled-bandwidth {
         type uint64;
         units "Kbps";
         description
           "Bandwidth values, expressed in kilobits per second.";
       }
     }

     container link-attributes {
       description
         "Definition of link attributes.";
       list link {
         key "source-node destination-node";
         description
           "Definition of link attributes.";
         leaf source-node {
           type nw:node-id;
           description
             "Indicates the source node identifier.";
         }
         leaf destination-node {
           type nw:node-id;
           description
             "Indicates the source node identifier.";
         }

         leaf default-bandwidth {
           type uint64;
           units "Kbps";
           description
             "Default bandwidth values when unspecified.";
         }

         choice time-variant-type {
           description
             "Controls the schedule type.";
           case period {
             uses schedule:period-of-time;

Ma, et al.               Expires 18 October 2024               [Page 39]
Internet-Draft            Common Schedule YANG                April 2024

           }
           case recurrence {
             uses schedule:recurrence-with-date-times {
               augment "date-times-choice/period-timeticks"
                     + "/period-timeticks" {
                 description
                   "Specifies the attributes inside each
                    period-timeticks entry.";
                 uses link-bandwidth-grouping;
               }
               augment "date-times-choice/period/period" {
                 description
                   "Specifies the attributes within each period entry.";
                 uses link-bandwidth-grouping;
               }
             }
           }
         }
       }
     }
   }

   Figure 18 shows a configuration example of a link's bandwidth that is
   scheduled between 2023/12/01 0:00 UTC to the end of 2023/12/31 with a
   daily schedule.  In each day, the bandwidth value is scheduled to be
   500 Kbps between 1:00 AM to 6:00 AM and 800 Kbps between 10:00 PM to
   11:00 PM.  The bandwidth value that's not covered by the period above
   is 1000 Kbps by default.

Ma, et al.               Expires 18 October 2024               [Page 40]
Internet-Draft            Common Schedule YANG                April 2024

   <?xml version="1.0" encoding="utf-8"?>
   <link-attributes
     xmlns="http://example.com/example-scheduled-link-bandwidth"
     xmlns:schedule="urn:ietf:params:xml:ns:yang:ietf-schedule">
     <link>
       <source-node>ne1</source-node>
       <destination-node>ne2</destination-node>
       <default-bandwidth>1000</default-bandwidth>
       <recurrence-first>
         <date-time-start>2023-12-01T01:00:00Z</date-time-start>
       </recurrence-first>
       <frequency>schedule:daily</frequency>
       <until>2023-12-31T23:59:59Z</until>
       <period-timeticks>
         <period-start>360000</period-start>
         <period-end>2160000</period-end>
         <scheduled-bandwidth>500</scheduled-bandwidth>
       </period-timeticks>
       <period-timeticks>
         <period-start>7920000</period-start>
         <period-end>8280000</period-end>
         <scheduled-bandwidth>800</scheduled-bandwidth>
       </period-timeticks>
     </link>
   </link-attributes>

              Figure 18: Example of Scheduled Link's Bandwidth

Acknowledgments

   This work is derived from the [I-D.ietf-opsawg-ucl-acl].  There is a
   desire from the OPSAWG to see this model be separately defined for
   wide use in scheduling context.

   Thanks to Adrian Farrel, Wei Pan, Tianran Zhou, and Joe Clarke for
   their valuable comments and inputs to this work.

   Many thanks to the authors of [I-D.united-tvr-schedule-yang],
   [I-D.contreras-opsawg-scheduling-oam-tests], and
   [I-D.ietf-netmod-eca-policy] for the constructive discussion during
   IETF#118.

Authors' Addresses

Ma, et al.               Expires 18 October 2024               [Page 41]
Internet-Draft            Common Schedule YANG                April 2024

   Qiufang Ma (editor)
   Huawei
   101 Software Avenue, Yuhua District
   Jiangsu
   210012
   China
   Email: maqiufang1@huawei.com

   Qin Wu
   Huawei
   101 Software Avenue, Yuhua District
   Jiangsu
   210012
   China
   Email: bill.wu@huawei.com

   Mohamed Boucadair (editor)
   Orange
   35000 Rennes
   France
   Email: mohamed.boucadair@orange.com

   Daniel King
   Lancaster University
   United Kingdom
   Email: d.king@lancaster.ac.uk

Ma, et al.               Expires 18 October 2024               [Page 42]