A Common YANG Data Model for Scheduling
Internet-Draft draft-ietf-netmod-schedule-yang-03
Qiufang Ma, Ed.
Huawei
101 Software Avenue, Yuhua District
Jiangsu
210012
China
maqiufang1@huawei.com
Qin Wu
Huawei
101 Software Avenue, Yuhua District
Jiangsu
210012
China
bill.wu@huawei.com
Mohamed Boucadair, Ed.
Orange
Rennes
35000
France
mohamed.boucadair@orange.com
Daniel King
Lancaster University
United Kingdom
d.king@lancaster.ac.uk
10 October 2024
Operations and Management
netmod
calendaring
scheduling
YANG
groupings
This document defines a common schedule YANG module which is designed to be applicable for scheduling purposes such as event, policy, services, or resources based on date and time. For the sake of better modularity, the module includes a set of recurrence related groupings with varying granularity levels (i.e., from basic to advanced).
Discussion Venues
This note is to be removed before publishing as an RFC.
Discussion of this document takes place on the Network Modeling (NETMOD) Working Group mailing list (netmod@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/netmod/.
Source for this draft and an issue tracker can be found at https://github.com/netmod-wg/schedule-yang.
Introduction
This document defines a common schedule YANG module ("ietf-schedule") that can be used in several scheduling contexts, e.g., (but not limited to) [I-D.ietf-opsawg-ucl-acl], [I-D.contreras-opsawg-scheduling-oam-tests], and [I-D.ietf-tvr-schedule-yang]. The module includes a set of reusable groupings which are designed to be applicable for scheduling purposes such as event, policy, services or resources based on date and time.
This document does not make any assumption about the nature of actions that are triggered by the schedules. Detection and resolution of any schedule conflicts are beyond the scope of this document.
Section 5 discusses relationship with the managed objects defined in [RFC3231].
Appendix A describes a set of examples to illustrate the use of the common schedule groupings (Section 3.3). And Appendix B provides sample modules to exemplify how future modules can use the extensibility provisions in "ietf-schedule" (Section 6). Also, Appendix C provides an example of using "ietf-schedule" module for scheduled use of resources framework (e.g., [RFC8413]).
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
- 2024-04-16 --> the actual date of the publication of this document
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].
This document uses the YANG terminology defined in Section 3 of [RFC7950].
The document makes use of the following terms:
Frequency:
Characterizes the type of a recurrence rule. Values are taken from "FREQ" rule in Section 3.3.10 of [RFC5545].
For example, repeating events based on an interval of a second or more are classified as recurrence with a frequency value of "secondly".
icalendar:
Refers to Internet Calendaring per [RFC5545].
Interval:
Refers to an integer that specifies at which intervals a recurrence rule repeats. Values are taken from "INTERVAL" rule in Section 3.3.10 of [RFC5545].
For example, "1", means every second for a secondly rule, every minute for a minutely rule, every hour for an hourly rule, etc.
System:
Refers to an entity that host a schedule that is managed using the YANG module defined in this document.
Module Overview
Features
The "ietf-schedule" data model defines the recurrence related groupings using a modular approach. To that aim, a variety of representations of recurrence groupings ranging from basic to advanced (iclander like) are defined. To allow for different options, two features are defined in the data model:
- "basic-recurrence"
- "icalendar-recurrence"
Refer to Section 3.4 for the use of these features.
Types and Identities
The "ietf-schedule" module (Section 6) defines the following identities:
- "frequency-type": Characterizes the repeating interval rule of a schedule (per second, per minute, etc.).
- "schedule-type": Indicates the type of a schedule. The following types are defined so far:
  - one-shot: The schedule will trigger an action without the duration/end time being specified and then the schedule will disable itself (Section 3.3 of [RFC3231]).
  - period: The schedule is a period-based schedule consisting either a start and end or a start and positive duration of time.
  - recurrence: This type is used for a recurrence-based schedule. A recurrence may be periodic (i.e., repeat over the same period, e.g., every five minutes) or not (i.e., repeat in a non-regular manner, e.g., every day at 8 and 9 AM).
- "schedule-state": Indicates the status of a schedule (enabled, disabled, conflicted, finished, etc.). This identity can also be used to manage the state of individual instances of a recurrence-based schedule.
- "discard-action": Specifies the action to perform when a schedule is discarded (e.g., generate a warning or an error message).
Groupings
The "ietf-schedule" module (Section 6) defines the following groupings:
- "generic-schedule-params" (Section 3.3.1)
- "period-of-time" (Section 3.3.2)
- "recurrence-basic" (Section 3.3.3)
- "recurrence-utc" (Section 3.3.4)
- "recurrence-with-time-zone" (Section 3.3.5)
- "recurrence-utc-with-date-times" (Section 3.3.6)
- "recurrence-time-zone-with-date-times" (Section 3.3.7)
- "icalendar-recurrence" (Section 3.3.8)
- "schedule-status" and "schedule-status-with-name" (Section 3.3.9)
Figure 1 provides an overview of the tree structure of the "ietf-schedule" module in terms of its groupings.
Overall Schedule Tree Structure

module: ietf-schedule

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

Each of these groupings is presented in the following subsections. Examples are provided in Appendix A.
The "generic-schedule-params" Grouping
A system accepts and handles the schedule requests, which may help further automate the scheduling process of events, policy, services, or resources based on date and time. The "generic-schedule-params" grouping (Figure 2) specifies a set of configuration parameters that are used by a system for validating requested schedules.
Generic Schedule Configuration Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    +-- description?            string
    +-- 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?         identityref
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

The "description" includes a description of the schedule. No constraint is imposed on the structure nor the use of this parameter.
The "time-zone-identifier" parameter, if provided, specifies the time zone reference of the date and time values with local time format.
The "validity" parameter specifies the date and time after which a schedule will be considered as invalid. It determines the latest time that a schedule can be executed by a system and takes precedence over similar attributes that are provided at the schedule instance itself.
The "max/min-allowed-start" parameters specify the maximum/minimum scheduled start date and time, a requested schedule will be rejected if the first occurrence of the schedule is later/earlier than the configured values.
The "max-allowed-end" parameter specifies the maximum allowed end time of the last occurrence. A requested schedule will be rejected if the end time of last occurrence is later than the configured "max-allowed-end" value.
The "discard-action" parameter specifies the action if a requested schedule is considered inactive or out-of-date.
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.
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.
The "period-description" includes a description of the period. No constraint is imposed on the structure nor the use of this parameter.
Period of Time Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    +-- period-description?     string
    +-- 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-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

The "recurrence-basic" Grouping
The "recurrence-basic" grouping (Figure 4) specifies a simple recurrence rule.
recurrence Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    +-- recurrence-description?   string
    +-- frequency                 identityref
    +-- interval?                 uint32
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

The frequency ("frequency") which is mandatory, identifies the type of recurrence rule. For example, a "daily" frequency value specifies repeating events based on an interval of a day or more.
Consistent with Section 3.3.10 of [RFC5545], the interval ("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 default value is "1", meaning every second for a secondly recurrence rule, every minute for a minutely rule, every hour for an hourly rule, every day for a daily rule, and so on. Note that per Section 4.13 of [I-D.ietf-netmod-rfc8407bis], no "default" substatement is used here because there are cases (e.g., profiling) where the use of the default is problematic.
The "recurrence-description" includes a description of the period. No constraint is imposed on the structure nor the use of this parameter.
The "recurrence-utc" Grouping
The "recurrence-utc" grouping (Figure 5) uses the "recurrence-basic" grouping and specifies a simple recurrence rule in UTC format.
recurrence-utc Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    +-- recurrence-first
    |  +-- start-time-utc?   yang:date-and-time
    |  +-- duration?         uint32
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- utc-until?          yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency                 identityref
    +-- interval?                 uint32
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

The "start-time-utc" indicates the start time in UTC format.
The "duration" parameter specifies, in units of seconds, the time period of the first occurrence. Unless specified otherwise, the "duration" also applies to subsequent recurrence instances.
Note that the "interval" and "duration" cover two distinct properties of a schedule event. The interval specifies when a schedule will occur, combined with the frequency parameter; while the duration indicates how long an occurence will last.
The repetition can be scoped by a specified end time or by a count of occurrences, indicated by the "recurrence-end" choice. The "start-time-utc" value always counts as the first occurrence.
The "recurrence-utc" grouping is designed to be reused in scheduling contexts where machine readability is more desirable.
The "recurrence-with-time-zone" Grouping
The "recurrence-with-time-zone" grouping (Figure 6) uses the "recurrence-basic" grouping and specifies a simple recurrence rule with a time zone.
recurrence-with-time-zone Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    +-- recurrence-first
    |  +-- start-time?             yang:date-and-time
    |  +-- duration?               duration
    |  +-- time-zone-identifier?   sys:timezone-name
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- until?              yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency                 identityref
    +-- interval?                 uint32
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

The "recurrence-first" container includes "start-time" and "duration" parameters to specify the start time and period of the first occurrence. Unless specified otherwise, the "duration" also applies to subsequent recurrence instances. It also includes a "time-zone-identifier" parameter which MUST be specified if the date and time value is neither reported in the format of UTC nor time zone offset to UTC.
The repetition can be scoped by a specified end time or by a count of occurrences, indicated by the "recurrence-end" choice. The "start-time" value always counts as the first occurrence.
Unlike the definition of "recurrence-utc" grouping (Section 3.3.4), "recurrence-with-time-zone" is intended to promote human readability over machine readability.
The "recurrence-utc-with-date-times" Grouping
The "recurrence-utc-with-date-times" grouping (Figure 7) uses the "recurrence-utc" grouping (Section 3.3.4) and adds a "period-timeticks" list to define an aggregate set of repeating occurrences.
recurrence-utc-with-date-times Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    +-- recurrence-first
    |  +-- start-time-utc?   yang:date-and-time
    |  +-- duration?         uint32
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- utc-until?          yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency                 identityref
    +-- interval?                 uint32
    +-- period-timeticks* [period-start]
       +-- period-start    yang:timeticks
       +-- period-end?     yang:timeticks
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

The recurrence instances are specified by the union of occurrences defined by both the recurrence rule and "period-timeticks" list. Duplicate instances are ignored. The value of the "period-start" instance must not exceed the value indicated by the value of "frequency" instance, e.g., the timeticks value must not exceed 100 in a secondly recurrence rule, and it must not exceed 6000 in a minutely recurrence rule, and so on.
The "recurrence-time-zone-with-date-times" Grouping
The "recurrence-time-zone-with-date-times" grouping (Figure 8) uses the "recurrence-with-time-zone" grouping (Section 3.3.5) and adds a "period" list to define an aggregate set of repeating occurrences.
recurrence-time-zone-with-date-times Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    +-- recurrence-first
    |  +-- start-time?             yang:date-and-time
    |  +-- duration?               duration
    |  +-- time-zone-identifier?   sys:timezone-name
    +-- (recurrence-bound)?
    |  +--:(until)
    |  |  +-- until?              yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency                 identityref
    +-- interval?                 uint32
    +-- period* [period-start]
       +-- period-description?     string
       +-- 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:
    ...
  grouping schedule-status-with-name:
    ...

The recurrence instances are specified by the union of occurrences defined by both the recurrence rule and "period" list. Duplicate instances are ignored.
The "icalendar-recurrence" Grouping
The "icalendar-recurrence" grouping (Figure 9) uses the "recurrence-time-zone-with-date-times" grouping (Section 3.3.7) and define more data nodes to enrich the definition of recurrence. The structure of the "icalendar-recurrence" grouping refers to the definition of recurrence component defined in Sections 3.3.10 and 3.8.5 of [RFC5545].
icalendar-recurrence Grouping Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    +-- recurrence-first
    |  +-- start-time?             yang:date-and-time
    |  +-- duration?               duration
    |  +-- time-zone-identifier?   sys:timezone-name
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- until?              yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency                 identityref
    +-- interval?                 uint32
    +-- period* [period-start]
    |  +-- period-description?     string
    |  +-- 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*          yang:date-and-time
  grouping schedule-status:
    ...
  grouping schedule-status-with-name:
    ...

An array of the "bysecond" (or "byminute", "byhour") specifies a list of seconds within a minute (or minutes within an hour, hours of the day). For example, within a "minutely" recurrence rule, the values of "byminute" node "10" and "20" means the occurrences generates at the 10th and 20th minute within an hour, reducing the number of recurrence instances from all minutes.
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). For example, within a "yearly" recurrence rule, the values of "byyearmonth" instance "1" and "2" means the occurrences generates in January and February, increasing the "yearly" recurrence from every year to every January and February 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.
The "schedule-status" and "schedule-status-with-name" Groupings
The "schedule-status" and "schedule-status-with-name" groupings (Figure 10) define common parameters for scheduling management/status exposure. The "schedule-status-with-name" grouping has the same structure as "schedule-status" but with an additional parameter to identify a schedule "schedule-id". Both structures are defined in the module to allow for better modularity and flexibility.
Schedule Status with and without Name Groupings Tree Structure

module: ietf-schedule

  grouping generic-schedule-params:
    ...
  grouping period-of-time:
    ...
  grouping recurrence-basic:
    ...
  grouping recurrence-utc:
    ...
  grouping recurrence-with-time-zone:
    ...
  grouping recurrence-utc-with-date-times:
    ...
  grouping recurrence-time-zone-with-date-times:
    ...
  grouping icalendar-recurrence:
    ...
  grouping schedule-status:
    +-- state?                    identityref
    +-- version?                  uint16
    +-- schedule-type?            identityref
    +--ro local-time?               yang:date-and-time
    +--ro last-update?              yang:date-and-time
    +--ro counter?                  yang:counter32
    +--ro last-occurrence?          yang:date-and-time
    +--ro upcoming-occurrence?      yang:date-and-time
    +--ro last-failed-occurrence?   yang:date-and-time
    +--ro failure-counter?          yang:counter32
  grouping schedule-status-with-name:
    +-- schedule-id?              string
    +-- state?                    identityref
    +-- version?                  uint16
    +-- schedule-type?            identityref
    +--ro local-time?               yang:date-and-time
    +--ro last-update?              yang:date-and-time
    +--ro counter?                  yang:counter32
    +--ro last-occurrence?          yang:date-and-time
    +--ro upcoming-occurrence?      yang:date-and-time
    +--ro last-failed-occurrence?   yang:date-and-time
    +--ro failure-counter?          yang:counter32

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. For a recurrence-based schedule, it represents the state of the overall recurrence. The "identityref" type is used for this parameter to allow extensibility in future modules.
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".
"local-time" reports the actual local time as seen by the entity that host a schedule. This paramter can be used by a controller to infer the offset to UTC.
"last-failed-occurrence" and "failure-counter" report the last failure that occured and the count of failures for this schedule.
The current groupings capture common parameters that are 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.
Features Use and Augmentations
Appendix B.1 provides an example about how the features defined in Section 3.1 can 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.
The common schedule groupings (Section 3.3) 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.
Some Usage Restrictions
There are some restrictions that need to be followed when using groupings defined in the "ietf-schedule" YANG module (Section 3.3):
- The instant in time represented by "period-start" MUST be before the "period-end" for "period-of-time" grouping (Section 3.3.2).
- The combination of the day, month, and year represented for date and time values 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 values.
- Schedules received with a starting time in the past with respect to current time SHOULD be ignored.
Relationship to the DISMAN-SCHEDULE-MIB
[RFC3231] specifies a Management Information Base (MIB) used to schedule management operations periodically or at specified dates and times.
Despite no data nodes are defined in this document, Table 1 lists how main objects in the DISMAN-SCHEDULE-MIB can be mapped to YANG parameters.
YANG/MIB Mapping
MIB Object | YANG
schedLocalTime | local-time
schedType | schedule-type
schedName | schedule-id
schedOwner | Not Supported
schedDescr | description
schedInterval | interval
schedWeekDay | weekday
schedMonth | byyearmonth
schedDay | bymonthday
schedHour | byhour
schedMinute | byminute
schedContextName | Not Supported
schedAdminStatus | state
schedOperStatus | state
schedFailures | failure-counter
schedLastFailure | Not Supported
schedLastFailed | last-failed-occurrence
schedStorageType | Not Supported
schedVariable | Not applicable
schedValue | Not applicable
schedTriggers | counter/failure-counter
The "ietf-schedule" YANG Module
This module imports types defined in [RFC6991] and [RFC7317].

module ietf-schedule {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-schedule";
  prefix schedule;

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

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

  organization
    "IETF NETMOD Working Group";
  contact
    "WG Web: <https://datatracker.ietf.org/wg/netmod/>
     WG List: <mailto:netmod@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 a set of common types and groupings
     which are applicable for scheduling purposes such as events,
     policy, services, or resources based on date and time.

     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 2024-04-16 {
    description
      "Initial revision.";
    reference
      "RFC XXXX: A Common YANG Data Model for Scheduling";
  }

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

  feature icalendar-recurrence {
    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
      "Indicates a repeating rule based on an interval of
       a second or more.";
  }

  identity minutely {
    base frequency-type;
    description
      "Indicates a repeating rule based on an interval of
       a minute or more.";
  }

  identity hourly {
    base frequency-type;
    description
      "Indicates a repeating rule based on an interval of
       an hour or more.";
  }

  identity daily {
    base frequency-type;
    description
      "Indicates a repeating rule based on an interval of
       a day or more.";
  }

  identity weekly {
    base frequency-type;
    description
      "Indicates a repeating rule based on an interval of
       a week or more.";
  }

  identity monthly {
    base frequency-type;
    description
      "Indicates a repeating rule based on an interval of
       a month or more.";
  }

  identity yearly {
    base frequency-type;
    description
      "Indicates a repeating rule based on an interval of
       a year or more.";
  }

  identity schedule-type {
    description
      "Base identity for schedule type.";
  }

  identity one-shot {
    base schedule-type;
    description
      "Indicates a one-shot schedule. That is a schedule that
       will trigger an action without the duration/end time being
       specified and then the schedule will disable itself.";
  }

  identity period {
    base schedule-type;
    description
      "Indicates a period-based schedule consisting either a
       start and end or a start and positive duration of time.";
  }

  identity recurrence {
    base schedule-type;
    description
      "Indicates a recurrence-based schedule.";
  }

  identity schedule-state {
    description
      "Base identity for schedule state.";
  }

  identity enabled {
    base schedule-state;
    description
      "Indicates a schedule with an enabled state.";
  }

  identity finished {
    base schedule-state;
    description
      "Indicates a schedule with a finished state.
       The finished state indicates that the schedule has ended.";
  }

  identity disabled {
    base schedule-state;
    description
      "Indicates a schedule with a disabled state.";
  }

  identity out-of-date {
    base schedule-state;
    description
      "Indicates a schedule with an out-of-date state.";
  }

  identity conflicted {
    base schedule-state;
    description
      "Indicates a schedule with a conflicted state with other
       schedules.";
  }

  identity discard-action {
    description
      "Indicates that a schedule will be discarded.";
  }

  identity warning {
    base discard-action;
    description
      "Indicates that a warning message is generated
       when a schedule is discarded.";
  }

  identity error {
    base discard-action;
    description
      "Indicates that an error message is generated
       when a schedule is discarded.";
  }

  identity silently-discard {
    base discard-action;
    description
      "Indicates that an invalid schedule is silently
       discarded.";
  }

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

       Such parameters are used as guards to prevent, e.g., stale
       configuration.";
    leaf description {
      type string;
      description
        "Provides a description of the schedule.";
    }
    leaf time-zone-identifier {
      type sys:timezone-name;
      description
        "Indicates the identifier for the time zone.";
    }
    leaf validity {
      type yang:date-and-time;
      description
        "Specifies the date and time after which a schedule will
         be considered as invalid. This parameter 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 maximum scheduled start date and time.
         A requested schedule whose first instance occurs after
         this value cannot be accepted by the entity. Specifically,
         a requested schedule will be rejected if the first
         occurrence of that schedule exceeds 'max-allowed-start'.";
    }
    leaf min-allowed-start {
      type yang:date-and-time;
      description
        "Specifies the minimum scheduled start date and time.
         A requested schedule whose first instance occurs before
         this value cannot be accepted by the entity. Specifically,
         a requested schedule will be rejected if the first
         occurrence of that schedule is scheduled before
         'min-allowed-start'.";
    }
    leaf max-allowed-end {
      type yang:date-and-time;
      description
        "A requested schedule will be rejected if the end time of
         the last occurrence exceeds 'max-allowed-end'.";
    }
    leaf discard-action {
      type identityref {
        base discard-action;
      }
      description
        "Specifies the behavior when a schedule is discarded when
         enforcing the guards in this grouping or it is received
         out-of-date.";
    }
  }

  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-description {
      type string;
      description
        "Provides a description of the period.";
    }
    leaf period-start {
      type yang:date-and-time;
      mandatory true;
      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-basic {
    description
      "A simple definition of recurrence.";
    leaf recurrence-description {
      type string;
      description
        "Provides a description of the recurrence.";
    }
    leaf frequency {
      type identityref {
        base frequency-type;
      }
      mandatory true;
      description
        "Specifies 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.
         The default value is '1', means every second for a
         'secondly' recurrence rule, every minute for a 'minutely'
         rule, and so on.";
    }
  }

  grouping recurrence-utc {
    description
      "A simple definition of recurrence with time specified in
       UTC. This grouping is intended to be machine-friendly.";
    container recurrence-first {
      description
        "Specifies the first instance of the recurrence.";
      leaf start-time-utc {
        type yang:date-and-time;
        description
          "Defines the instant date and time of the first instance
           in the recurrence set. A UTC format MUST be used.";
      }
      leaf duration {
        type uint32;
        units "seconds";
        description
          "When specified, it indicates how long the first occurrence
           last. Unless specified otherwise, it also applies to all
           the other instances in the recurrence set.";
      }
    }
    choice recurrence-end {
      description
        "Modes to control the end of a recurrence rule. If no
         choice is indicated, the recurrence rule is considered
         to repeat forever.";
      case until {
        description
          "This case defines a way that limits the end of a
           recurrence rule in an inclusive manner.";
        leaf utc-until {
          type yang:date-and-time;
          description
            "This parameter specifies a date and time value to
             inclusively terminate the recurrence in UTC format. If
             the value specified by this parameter is synchronized
             with the specified recurrence, it becomes the last
             instance of the recurrence.";
        }
      }
      case count {
        description
          "This case defines the number of occurrences at which
           to terminate the recurrence.";
        leaf count {
          type uint32;
          description
            "The positive number of occurrences at which to
             terminate the recurrence.";
        }
      }
    }
    uses recurrence-basic;
  }

  grouping recurrence-with-time-zone {
    description
      "A simple definition of recurrence to specify the time
       with a local time and time zone identifier. This grouping
       is intended to be human-friendly.";
    container recurrence-first {
      description
        "Specifies the first instance of the recurrence.";
      leaf start-time {
        type yang:date-and-time;
        description
          "Defines the instant date and time of the first instance
           in the recurrence set.";
      }
      leaf duration {
        type duration;
        description
          "When specified, it indicates how long the first
           occurrence last. Unless specified otherwise, it also
           applies to all the other instances in the recurrence
           set.";
      }
      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-time' or 'until' value is neither reported in
           the format of UTC nor time zone offset to UTC.";
      }
    }
    choice recurrence-end {
      description
        "Modes to terminate the recurrence rule. If no choice is
         indicated, the recurrence rule is considered to repeat
         forever.";
      case until {
        description
          "The end of the recurrence is indicated by a specific
           date-and-time value.";
        leaf until {
          type yang:date-and-time;
          description
            "Specifies a date and time value to terminate the
             recurrence. If the value specified by this parameter
             is synchronized with the specified recurrence, it
             becomes the last instance of the recurrence.";
        }
      }
      case count {
        description
          "The end of the recurrence is indicated by the number
           of occurrences.";
        leaf count {
          type uint32;
          description
            "The positive number of occurrences at which to
             terminate the recurrence.";
        }
      }
    }
    uses recurrence-basic;
  }

  grouping recurrence-utc-with-date-times {
    description
      "This grouping defines an aggregate set of repeating
       occurrences with UTC time format. The recurrence instances
       are specified by the occurrences defined by both the
       recurrence rule and 'period-timeticks' list. Duplicate
       instances are ignored.";
    uses recurrence-utc;
    list period-timeticks {
      key "period-start";
      description
        "A list of periods 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 schedule within one recurrence.";
      }
      leaf period-end {
        type yang:timeticks;
        description
          "End time of the schedule within one recurrence.";
      }
    }
  }

  grouping recurrence-time-zone-with-date-times {
    description
      "This grouping defines an aggregate set of repeating
       occurrences with local time format and time zone specified.
       The recurrence instances are specified by the occurrences
       defined by both the recurrence rule and 'period' list.
       Duplicate instances are ignored.";
    uses recurrence-with-time-zone;
    list period {
      key "period-start";
      description
        "A list of periods with date-and-time formats.";
      uses period-of-time;
    }
  }

  grouping icalendar-recurrence {
    description
      "This grouping specifies properties of a recurrence rule.";
    reference
      "RFC 5545: Internet Calendaring and Scheduling Core Object
                 Specification (iCalendar), Section 3.8.5";
    uses recurrence-time-zone-with-date-times;
    leaf-list bysecond {
      type uint32 {
        range "0..60";
      }
      description
        "Specifies a list of seconds within a minute.";
    }
    leaf-list byminute {
      type uint32 {
        range "0..59";
      }
      description
        "Specifies 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
          "Corresponds 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;
      description
        "Specifies the day on which the workweek starts. The
         default value is 'monday'.";
    }
    leaf-list exception-dates {
      type yang:date-and-time;
      description
        "Defines a list of exceptions for recurrence.";
    }
  }

  grouping schedule-status {
    description
      "This grouping defines common properties of scheduling
       status.";
    leaf state {
      type identityref {
        base schedule-state;
      }
      description
        "Indicates the current state of the schedule.";
    }
    leaf version {
      type uint16;
      description
        "Indicates the version number of the schedule.";
    }
    leaf schedule-type {
      type identityref {
        base schedule-type;
      }
      description
        "Indicates the schedule type.";
    }
    leaf local-time {
      type yang:date-and-time;
      config false;
      description
        "Reports the local time as used by the entity that
         hosts the schedule.";
    }
    leaf last-update {
      type yang:date-and-time;
      config false;
      description
        "Reports the timestamp that the schedule is last updated.";
    }
    leaf counter {
      when "derived-from-or-self(../schedule-type, "
         + "'schedule:recurrence')";
      type yang:counter32;
      config false;
      description
        "The number of occurrences while invoking the scheduled
         action successfully. The count wraps around when it reaches
         the maximum value.";
    }
    leaf last-occurrence {
      when "derived-from-or-self(../schedule-type, "
         + "'schedule:recurrence')";
      type yang:date-and-time;
      config false;
      description
        "Indicates 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
        "Indicates the timestamp of next occurrence.";
    }
    leaf last-failed-occurrence {
      when "derived-from-or-self(../schedule-type, "
         + "'schedule:recurrence')";
      type yang:date-and-time;
      config false;
      description
        "Indicates the timestamp of last failed action triggered by
         the schedule.";
    }
    leaf failure-counter {
      when "derived-from-or-self(../schedule-type, "
         + "'schedule:recurrence')";
      type yang:counter32;
      config false;
      description
        "Counts the number of failures while invoking the scheduled
         action.";
    }
  }

  grouping schedule-status-with-name {
    description
      "This grouping defines common properties of scheduling
       status.";
    leaf schedule-id {
      type string;
      description
        "The schedule identifier that uniquely identifies a
         schedule within a device, controller, network, etc.
         The unicity scope depends on the implementation.";
    }
    uses schedule-status;
  }
}

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.
Care must be taken when defining recurrences occurring very often and frequent that can be an additional source of attacks by keeping the system permanently busy with the management of scheduling.
IANA Considerations
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.

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

References
Normative References
[RFC3231]

Definitions of Managed Objects for Scheduling Management Operations
D. Levi
J. Schoenwaelder
January 2002
RFC 3231
DOI 10.17487/RFC3231
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
[RFC7950]

The YANG 1.1 Data Modeling Language
M. Bjorklund, Ed.
August 2016
RFC 7950
DOI 10.17487/RFC7950
[RFC5545]

Internet Calendaring and Scheduling Core Object Specification (iCalendar)
B. Desruisseaux, Ed.
September 2009
RFC 5545
DOI 10.17487/RFC5545
[RFC6991]

Common YANG Data Types
J. Schoenwaelder, Ed.
July 2013
RFC 6991
DOI 10.17487/RFC6991
[RFC7317]

A YANG Data Model for System Management
A. Bierman
M. Bjorklund
August 2014
RFC 7317
DOI 10.17487/RFC7317
[RFC6241]

Network Configuration Protocol (NETCONF)
R. Enns, Ed.
M. Bjorklund, Ed.
J. Schoenwaelder, Ed.
A. Bierman, Ed.
June 2011
RFC 6241
DOI 10.17487/RFC6241
[RFC8040]

RESTCONF Protocol
A. Bierman
M. Bjorklund
K. Watsen
January 2017
RFC 8040
DOI 10.17487/RFC8040
[RFC6242]

Using the NETCONF Protocol over Secure Shell (SSH)
M. Wasserman
June 2011
RFC 6242
DOI 10.17487/RFC6242
[RFC8446]

The Transport Layer Security (TLS) Protocol Version 1.3
E. Rescorla
August 2018
RFC 8446
DOI 10.17487/RFC8446
[RFC8341]

Network Configuration Access Control Model
A. Bierman
M. Bjorklund
March 2018
STD 91
RFC 8341
DOI 10.17487/RFC8341
[RFC3688]

The IETF XML Registry
M. Mealling
January 2004
BCP 81
RFC 3688
DOI 10.17487/RFC3688
[RFC6020]

YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)
M. Bjorklund, Ed.
October 2010
RFC 6020
DOI 10.17487/RFC6020
Informative References
[I-D.ietf-opsawg-ucl-acl]

A YANG Data Model and RADIUS Extension for Policy-based Network Access Control
Qiufang Ma
Huawei
Qin Wu
Huawei
Mohamed Boucadair
Orange
Daniel King
Lancaster University
25 June 2024
Internet-Draft draft-ietf-opsawg-ucl-acl-05
[I-D.contreras-opsawg-scheduling-oam-tests]

A YANG Data Model for Network Diagnosis by Scheduling Sequences of OAM Tests
Luis M. Contreras
Telefonica
Victor Lopez
Nokia
8 July 2024
Internet-Draft draft-contreras-opsawg-scheduling-oam-tests-02
[I-D.ietf-tvr-schedule-yang]

YANG Data Model for Scheduled Attributes
Yingzhen Qu
Futurewei Technologies
Acee Lindem
LabN Consulting, L.L.C.
Eric Kinzie
LabN Consulting, L.L.C.
Don Fedyk
LabN Consulting, L.L.C.
Marc Blanchet
Viagenie
22 July 2024
Internet-Draft draft-ietf-tvr-schedule-yang-02
[RFC8413]

Framework for Scheduled Use of Resources
Y. Zhuang
Q. Wu
H. Chen
A. Farrel
July 2018
RFC 8413
DOI 10.17487/RFC8413
[RFC8340]

YANG Tree Diagrams
M. Bjorklund
L. Berger, Ed.
March 2018
BCP 215
RFC 8340
DOI 10.17487/RFC8340
[I-D.ietf-netmod-rfc8407bis]

Guidelines for Authors and Reviewers of Documents Containing YANG Data Models
Andy Bierman
YumaWorks
Mohamed Boucadair
Orange
Qin Wu
Huawei
27 September 2024
Internet-Draft draft-ietf-netmod-rfc8407bis-17
[RFC3339]

Date and Time on the Internet: Timestamps
G. Klyne
C. Newman
July 2002
RFC 3339
DOI 10.17487/RFC3339
[RFC7951]

JSON Encoding of Data Modeled with YANG
L. Lhotka
August 2016
RFC 7951
DOI 10.17487/RFC7951
[RFC9657]

Time-Variant Routing (TVR) Use Cases
E. Birrane III
N. Kuhn
Y. Qu
R. Taylor
L. Zhang
October 2024
RFC 9657
DOI 10.17487/RFC9657
[I-D.ietf-netmod-eca-policy]

A YANG Data model for ECA Policy Management
Qin Wu
Huawei
Igor Bryskin
Individual
Henk Birkholz
Fraunhofer SIT
Xufeng Liu
Volta Networks
Benoît Claise
Cisco
19 February 2021
Internet-Draft draft-ietf-netmod-eca-policy-01
[I-D.liu-netmod-yang-schedule]

A YANG Data Model for Configuration Scheduling
Xufeng Liu
Jabil
Igor Bryskin
Huawei Technologies
Vishnu Pavan Beeram
Juniper Networks
Tarek Saad
Cisco Systems Inc
Himanshu C. Shah
Ciena
Oscar Gonzalez de Dios
Telefonica
1 March 2018
Internet-Draft draft-liu-netmod-yang-schedule-05
Examples of Format Representation
This section provides some examples to illustrate the use of the period and recurrence formats defined in Section 6. The following modules are used for illustration purposes:

module example-sch-usage-1 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-1";
  prefix "ex-schu-1";

  import ietf-schedule {
    prefix "schedule";
  }

  container generic-schedule-params {
    uses schedule:generic-schedule-params;
  }
  container schedule-status {
    uses schedule:schedule-status;
  }
}

module example-sch-usage-2 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-2";
  prefix "ex-schu2";

  import ietf-schedule {
    prefix "schedule";
  }

  container period-of-time {
    uses schedule:period-of-time;
  }
}

module example-sch-usage-3 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-3";
  prefix "ex-schu-3";

  import ietf-schedule {
    prefix "schedule";
  }

  container recurrence-basic {
    uses schedule:recurrence-basic;
  }
}

module example-sch-usage-4 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-4";
  prefix "ex-schu-4";

  import ietf-schedule {
    prefix "schedule";
  }

  container recurrence-utc {
    uses schedule:recurrence-utc;
  }
}

module example-sch-usage-5 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-5";
  prefix "ex-schu-5";

  import ietf-schedule {
    prefix "schedule";
  }

  container recurrence-with-time-zone {
    uses schedule:recurrence-with-time-zone;
  }
}

module example-sch-usage-6 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-6";
  prefix "ex-schu-6";

  import ietf-schedule {
    prefix "schedule";
  }

  container recurrence-utc-with-date-times {
    uses schedule:recurrence-utc-with-date-times;
  }
}

module example-sch-usage-7 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-7";
  prefix "ex-schu-8";

  import ietf-schedule {
    prefix "schedule";

  container recurrence-time-zone-with-date-times {
    uses schedule:recurrence-time-zone-with-date-times;
  }
}

module example-sch-usage-8 {
  yang-version 1.1;
  namespace "http://example.com/example-sch-usage-8";
  prefix "ex-schu-8";

  container icalendar-recurrence {
    uses schedule:icalendar-recurrence;
  }
}

For each example, only the message body is provided with JSON used for encoding per the guidance in [RFC7951].
The "generic-schedule-params" Grouping
Figure 11 illustrates the example of a requested schedule that needs to start no earlier than 08:00 AM, January 1, 2025 and end no later than 8:00 PM, January 31, 2025 (Beijing time). Schedule requests that fail to meet the requirements are ignored by the system as indicates by "discard-action".
Generic Parameters with 'max-allowed-end' for Schedule Validation

{
  "example-sch-usage-1:generic-schedule-params": {
    "time-zone-identifier": "China/Beijing",
    "min-allowed-start": "2025-01-01T08:00:00",
    "max-allowed-end": "2025-01-31T20:00:00",
    "discard-action": "ietf-schedule:silently-discard"
  }
}

To illustrate the difference between "max-allowed-end" and "validity" parameters, Figure 12 shows the example of a requested schedule that needs to start no earlier than 08:00 AM, January 1, 2025 (Paris time). Schedule requests that fail to meet the requirements are discarded with warning messages. The requested schedule may end after 8:00 PM, January 31, 2025, but any occurrences that are generated after that time would be considered as invalid.
Generic Parameters with 'validity' for Schedule Validation

{
  "example-sch-usage-1:generic-schedule-params": {
    "time-zone-identifier": "France/Paris",
    "validity": "2025-01-31T20:00:00",
    "min-allowed-start": "2025-01-01T08:00:00",
    "discard-action": "ietf-schedule:warning"
  }
}

The "period-of-time" Grouping
Figure 13 shows an 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.
Simple Start/End Schedule

{
  "example-sch-usage-2:period-of-time": {
    "period-start": "2025-01-01T08:00:00Z",
    "period-end": "2027-12-31T18:00:00Z"
  }
}

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 14.
Simple Schedule with Duration

{
  "example-sch-usage-2:period-of-time": {
    "period-start": "2025-01-01T08:00:00Z",
    "duration": "P15DT05:20:00"
  }
}

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 15.
Simple Schedule with Time Zone Indication

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

The "recurrence-basic" Grouping
Figure 18 indicates a recurrence of every 2 days which starts immediately and repeat forever:
Simple Schedule with Recurrence

{
  "example-sch-usage-3:recurrence-basic": {
    "recurrence-description": "forever recurrence rule",
    "frequency": "ietf-schedule:daily",
    "interval": 2
  }
}

The "recurrence-utc" Grouping
Figure 17 indicates a recurrence from 8:00 AM to 9:00 AM every day, from December 1 to December 31, 2025 in UTC:
Simple Schedule with Recurrence in UTC

{
  "example-sch-usage-4:recurrence-utc": {
    "recurrence-first": {
      "start-time-utc": "2025-12-01T08:00:00Z",
      "duration": 3600
    },
    "frequency": "ietf-schedule:daily",
    "interval": 1,
    "utc-until": "2025-12-31T23:59:59Z"
  }
}

The "recurrence-with-time-zone" Grouping
Figure 18 indicates a recurrence of every 2 hours for 10 occurrences, lasting 10 minutes, and starting at 3 p.m. on December 1, 2025 in New York:
Simple Schedule with Recurrence with Time Zone Indication

{
  "example-sch-usage-5:recurrence-with-time-zone": {
    "recurrence-first": {
      "start-time": "2025-12-01T15:00:00",
      "duration": "PT00:10:00",
      "time-zone-identifier": "America/New_York"
    },
    "frequency": "ietf-schedule:hourly",
    "interval": 2,
    "count": 10
  }
}

The "recurrence-utc-with-date-times" Grouping
Figure 19 indicates a recurrence that occurs every two days starting at 9:00 AM and 3:00 PM for a duration of 30 minutes and 40 minutes respectively, from 2025-06-01 to 2025-06-30 in UTC:
Example of Recurrence With Date Times

{
  "example-sch-usage-6:recurrence-utc-with-date-times": {
    "recurrence-first": {
      "start-time-utc": "2025-06-01T09:00:00Z"
    },
    "frequency": "ietf-schedule:daily",
    "interval": 2,
    "utc-until": "2025-06-30T23:59:59Z",
    "period-timeticks": [
      {
        "period-start": "3240000",
        "period-end": "3420000"
      },
      {
        "period-start": "5400000",
        "period-end": "5640000"
      }
    ]
  }
}

The "recurrence-time-zone-with-date-times" Grouping
Figure 20 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 (New York):
Example of Advanced Recurrence Schedule

{
  "example-sch-usage-7:recurrence-time-zone-with-date-times": {
    "recurrence-first": {
      "start-time": "2025-12-01T09:00:00",
      "duration": "PT00:15:00",
      "time-zone-identifier": "America/New_York"
    },
    "frequency": "ietf-schedule:minutely",
    "interval": 30,
    "until": "2025-12-01T17:00:00Z",
    "period": [
      {
        "period-start": "2025-12-01T18:00:00",
        "duration": "PT00:20:00"
      },
      {
        "period-start": "2025-12-01T18:30:00",
        "duration": "PT00:20:00"
      }
    ]
  }
}

The "icalendar-recurrence" Grouping
Figure 21 indicates 10 occurrences that occur at 8:00 AM (EST), every last Saturday of the month starting in January 2024:
Simple iCalendar Recurrence

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

Figure 22 is an example of a recurrence that occurs on the last workday of the month until December 25, 2025, from January 1, 2025:
Example of Advanced iCalendar Recurrence

{
  "example-sch-usage-8:icalendar-recurrence": {
    "recurrence-first": {
      "start-time": "2025-01-01"
    },
    "frequency": "ietf-schedule:monthly",
    "until": "2025-12-25",
    "byday": [
      {
        "weekday": "monday"
      },
      {
        "weekday": "tuesday"
      },
      {
        "weekday": "wednesday"
      },
      {
        "weekday": "thursday"
      },
      {
        "weekday": "friday"
      }
    ],
    "bysetpos": [
      -1
    ]
  }
}

Figure 23 indicates a recurrence that occurs 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:
Example of Advanced iCalendar Recurrence with Exceptions

{
  "example-sch-usage-8:icalendar-recurrence": {
    "recurrence-first": {
      "start-time": "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"
    ]
  }
}

The "schedule-status" Grouping
Figure 24 indicates the scheduled recurrence status of Figure 23 at the time of 12:15 PM, 2025-12-01 (UTC):
Example of a Schedule Status

{
  "example-sch-usage-1:schedule-status": {
    "state": "ietf-schedule:enabled",
    "version": 1,
    "schedule-type": "ietf-schedule:recurrence",
    "counter": 9,
    "last-occurrence": [
      "2025-12-01T12:00:00Z"
    ],
    "upcoming-occurrence": [
      "2025-12-01T12:20:00Z"
    ]
  }
}

At the time of 12:15 PM, 2025-12-01 (UTC), the recurring event occurred at (note that occurrence at 10:20 AM is excluded): 9:00, 9:20, 9:40, 10:00, 10:40, 11:00, 11:20, 11:40, 12:00. The last occurrence was at 12:00, the upcoming one is at 12:20.
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.
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.";
    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.";
        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;
        description
          "Basic recurrence schedule specification, only applies when
           schedule:basic-recurrence feaure is supported.";
        leaf schedule-id {
          type string;
          description
            "The schedule identifier for this recurrence rule.";
        }
        uses schedule:recurrence-basic;
       }

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

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

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., [RFC9657]. The following example module which augments the "recurrence-utc-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-utc-with-date-times {
            augment "period-timeticks" {
              description
                "Specifies the attributes inside each
                 period-timeticks entry.";
              uses link-bandwidth-grouping;
            }
          }
        }
      }
    }
  }
}

Figure 25 shows a configuration example of a link's bandwidth that is scheduled between 2025-12-01 0:00 UTC to the end of 2025-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.
Example of Scheduled Link's Bandwidth

<?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>
      <utc-start-time>2025-12-01T01:00:00Z</utc-start-time>
    </recurrence-first>
    <frequency>schedule:daily</frequency>
    <utc-until>2025-12-31T23:59:59Z</utc-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>

Examples of Using "ietf-schedule" Module for Scheduled Use of Resources Framework
This section exemplifies how the architecture for supporting scheduled reservation of Traffic Engineering (TE) resources in [RFC8413] might leverage the "period-of-time" grouping defined in the "ietf-schedule" module to implement scheduled use of resources.
The following example module shows how a scheduled link capacity reservation could be defined.

module example-sch-capacity-res {
  yang-version 1.1;
  namespace "http://example.com/example-sch-capacity-res";
  prefix "ex-schecaparev";

  import ietf-network-topology {
    prefix "nt";
  }

  import ietf-schedule {
    prefix "schedule";
  }

  container link-capability-reservations {
    list scheduled-link-capacity {
      key "schedule-id";
      leaf schedule-id {
        type string;
      }
      leaf link-id {
        type nt:link-id;
      }
      leaf reserved-capability {
        type uint64;
        units "Mbps";
      }
      uses schedule:period-of-time;
    }
  }
}

Section 4 of [RFC8413] defines the reference architecture for scheduled use of resources, the service requester sends a request to a Path Computation Element (PCE) and includes the parameters of the Label Switched Path (LSP) that the requester wishes to supply, the configuration example to provide the scheduled resource is shown in Figure 26.
Example of Scheduled Link's Bandwidth Reservation

<?xml version="1.0" encoding="utf-8"?>
<link-capability-reservations
  xmlns="http://example.com/example-sch-capacity-res"
  xmlns:schedule="urn:ietf:params:xml:ns:yang:ietf-schedule">
   <scheduled-link-capacity>
      <schedule-id>1</schedule-id>
      <link-id>1-2-1</link-id>
      <reserved-capability>500</reserved-capability>
      <period-start>2025-03-10T08:00:00Z</period-start>
      <period-end>2025-03-10T09:00:00Z</period-end>
   </scheduled-link-capacity>
   <scheduled-link-capacity>
      <schedule-id>2</schedule-id>
      <link-id>2-1-1</link-id>
      <reserved-capability>400</reserved-capability>
      <period-start>2025-04-01T00:00:00Z</period-start>
      <duration>PT09:00:00</duration>
   </scheduled-link-capacity>
   <scheduled-link-capacity>
      <schedule-id>3</schedule-id>
      <link-id>2-1-1</link-id>
      <reserved-capability>500</reserved-capability>
      <period-start>2025-04-01T09:00:00Z</period-start>
      <period-end>2025-04-01T23:59:59Z</period-end>
   </scheduled-link-capacity>
</link-capability-reservations>

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, Joe Clarke, Steve Baillargeon, and Dhruv Dhody for their valuable comments and inputs to this work.
Many thanks to the authors of [I-D.ietf-tvr-schedule-yang], [I-D.contreras-opsawg-scheduling-oam-tests], and [I-D.ietf-netmod-eca-policy] for the constructive discussion during IETF#118.
Other related efforts were explored in the past, e.g., [I-D.liu-netmod-yang-schedule].
Thanks to Reshad Rahman for the great YANGDOCTORS review.