Internet-Draft Common Schedule YANG February 2024
Ma, et al. Expires 5 August 2024 [Page]
Workgroup:
OPSAWG
Internet-Draft:
draft-ma-opsawg-schedule-yang-03
Published:
Intended Status:
Standards Track
Expires:
Authors:
Q. Ma, Ed.
Huawei
Q. Wu
Huawei
M. Boucadair, Ed.
Orange
D. King
Lancaster University

A Common YANG Data Model for Scheduling

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 schedule 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 5 August 2024.

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" 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].

3. Module Overview

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

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

module: ietf-schedule

  grouping period-of-time:
    ...
  grouping recurrence:
    ...
  grouping recurrence-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
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 "period-of-time" Grouping

The "period-of-time" grouping (Figure 2) 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 (see Section 3.3.9 of [RFC5545]).

module: ietf-schedule

  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:
    ...
Figure 2: Period of Time Grouping Tree Structure

3.2. The "recurrence" Grouping

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

module: ietf-schedule

  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:
    ...
Figure 3: 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.

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

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

module: ietf-schedule

  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:
    ...
Figure 4: 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.4. The "icalendar-recurrence" Grouping

The "icalendar-recurrence" grouping (Figure 5) uses the "recurrence-with-date-times" grouping (Section 3.3) 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 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
    |  |     +-- 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
Figure 5: 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).

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.

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.

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. 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";
  }

  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";
  }

  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
          "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
       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.";
  }

  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;
      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 {
      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 {
      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
         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,"
             +"'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
        "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.";
    }
    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.";
    }
  }
}

<CODE ENDS>

6. Security Considerations

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.

7. IANA Considerations

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

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

8. References

8.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, , <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, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688]
Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, , <https://www.rfc-editor.org/info/rfc3688>.
[RFC5545]
Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, , <https://www.rfc-editor.org/info/rfc5545>.
[RFC6020]
Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, , <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, , <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242]
Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, , <https://www.rfc-editor.org/info/rfc6242>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/info/rfc7950>.
[RFC8040]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, , <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, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341]
Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, , <https://www.rfc-editor.org/info/rfc8341>.
[RFC8446]
Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, , <https://www.rfc-editor.org/info/rfc8446>.

8.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, , <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 Progress, Internet-Draft, draft-ietf-netmod-eca-policy-01, , <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-eca-policy-01>.
[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-02, , <https://datatracker.ietf.org/doc/html/draft-ietf-opsawg-ucl-acl-02>.
[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-04, , <https://datatracker.ietf.org/doc/html/draft-ietf-tvr-use-cases-04>.
[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-00, , <https://datatracker.ietf.org/doc/html/draft-united-tvr-schedule-yang-00>.
[RFC7951]
Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, , <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, , <https://www.rfc-editor.org/info/rfc8340>.

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

{
  "period-start": "2025-01-01T08:00:00Z",
  "period-end": "2027-12-01T18:00:00Z"
}
Figure 6: 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 7.

{
  "period-start": "2025-01-01T08:00:00Z",
  "duration": "P15DT05:20:00"
}
Figure 7: 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 8.

{
  "period-start": "2025-11-19T02:00:00",
  "time-zone-identifier": "America/Los_Angeles",
  "duration": "P20W"
}
Figure 8: Simple Schedule with Time Zone Indication

A.2. The "recurrence" Grouping

Figure 9 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:

{
  "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 9: Simple Schedule with Recurrence

Figure 10 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 10: Simple Schedule with Recurrence and End Date

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

Figure 11 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 11: Example of Recurrence With Date Times

Figure 12 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:

{
  "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 12: Example of Advanced Recurrence Schedule

A.4. The "icalendar-recurrence" Grouping

Figure 13 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 13: Simple iCalendar Recurrence

Figure 14 is an example of a recurrence that occurs on the last workday of the month until December 25, 2024, from January 1, 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 14: Example of Advanced iCalendar Recurrence

Figure 15 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 15: 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.

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.";

    choice local-or-remote {
      description
        "Specifies whether the configuration to be backed up is
         local or remote.";
      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.";
      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.";
      uses schedule:icalendar-recurrence;
    }
  }
}

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.";

  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;
        }
        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 16 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.

<?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 16: 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

Qiufang Ma (editor)
Huawei
101 Software Avenue, Yuhua District
Jiangsu
210012
China
Qin Wu
Huawei
101 Software Avenue, Yuhua District
Jiangsu
210012
China
Mohamed Boucadair (editor)
Orange
35000 Rennes
France
Daniel King
Lancaster University
United Kingdom