netmod Q. Ma, Ed. Internet-Draft Q. Wu Intended status: Standards Track Huawei Expires: 30 October 2024 M. Boucadair, Ed. Orange D. King Lancaster University 28 April 2024 A Common YANG Data Model for Scheduling draft-ietf-netmod-schedule-yang-01 Abstract 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 basic, intermediate, and advanced versions of recurrence related groupings. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 30 October 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components Ma, et al. Expires 30 October 2024 [Page 1] Internet-Draft Common Schedule YANG April 2024 extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Editorial Note (To be removed by RFC Editor) . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Module Overview . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. The "generic-schedule-params" Grouping . . . . . . . . . 5 3.2. The "period-of-time" Grouping . . . . . . . . . . . . . . 6 3.3. The "recurrence" Grouping . . . . . . . . . . . . . . . . 7 3.4. The "recurrence-utc" Grouping . . . . . . . . . . . . . . 9 3.5. The "recurrence-with-time-zone" Grouping . . . . . . . . 10 3.6. The "recurrence-utc-with-date-times" Grouping . . . . . . 11 3.7. The "recurrence-time-zone-with-date-times" Grouping . . . 12 3.8. The "icalendar-recurrence" Grouping . . . . . . . . . . . 14 3.9. The "schedule-status" Grouping . . . . . . . . . . . . . 16 4. Features and Augmentations . . . . . . . . . . . . . . . . . 17 5. Note and Restrictions . . . . . . . . . . . . . . . . . . . . 18 6. The "ietf-schedule" YANG Module . . . . . . . . . . . . . . . 18 7. Security Considerations . . . . . . . . . . . . . . . . . . . 33 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 8.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 34 8.2. The "YANG Module Names" Registry . . . . . . . . . . . . 34 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 9.2. Informative References . . . . . . . . . . . . . . . . . 36 Appendix A. Examples of Format Representation . . . . . . . . . 37 A.1. The "generic-schedule-params" Grouping . . . . . . . . . 37 A.2. The "period-of-time" Grouping . . . . . . . . . . . . . . 37 A.3. The "recurrence" Grouping . . . . . . . . . . . . . . . . 38 A.4. The "recurrence-utc" Grouping . . . . . . . . . . . . . . 38 A.5. The "recurrence-with-time-zone" Grouping . . . . . . . . 39 A.6. The "recurrence-utc-with-date-times" Grouping . . . . . . 39 A.7. The "recurrence-time-zone-with-date-times" Grouping . . . 40 A.8. The "icalendar-recurrence" Grouping . . . . . . . . . . . 41 A.9. The "schedule-status" Grouping . . . . . . . . . . . . . 42 Appendix B. Examples of Using/Extending the "ietf-schedule" Module . . . . . . . . . . . . . . . . . . . . . . . . . 42 B.1. Example: Schedule Tasks to Execute Based on a Recurrence Rule . . . . . . . . . . . . . . . . . . . . . . . . . . 42 B.2. Example: Schedule Network Properties to Change Based on Date and Time . . . . . . . . . . . . . . . . . . . . . . 45 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 Ma, et al. Expires 30 October 2024 [Page 2] Internet-Draft Common Schedule YANG April 2024 1. 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. 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 * 2024-04-16 --> the actual date of the publication of this document 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. The meanings of the symbols in tree diagrams are defined in [RFC8340]. Also, this document uses the YANG terminology defined in Section 3 of [RFC7950]. Ma, et al. Expires 30 October 2024 [Page 3] Internet-Draft Common Schedule YANG April 2024 3. Module Overview The "ietf-schedule" module (Section 6) defines the following groupings: * "generic-schedule-params" (Section 3.1) * "period-of-time" (Section 3.2) * "recurrence" (Section 3.3) * "recurrence-utc" (Section 3.4) * "recurrence-with-time-zone" (Section 3.5) * "recurrence-utc-with-date-times" (Section 3.6) * "recurrence-time-zone-with-date-times" (Section 3.7) * "icalendar-recurrence" (Section 3.8) * "schedule-status" (Section 3.9) Figure 1 provides an overview of the tree structure [RFC8340] of the "ietf-schedule" module in terms of its groupings. module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... grouping recurrence-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: ... Figure 1: Overall Schedule Tree Structure Ma, et al. Expires 30 October 2024 [Page 4] Internet-Draft Common Schedule YANG April 2024 Each of these groupings is presented in the following subsections. Examples are provided in Appendix A. 3.1. 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. module: ietf-schedule grouping generic-schedule-params: +-- time-zone-identifier? sys:timezone-name +-- validity? yang:date-and-time +-- max-allowed-start? yang:date-and-time +-- min-allowed-start? yang:date-and-time +-- max-allowed-end? yang:date-and-time +-- discard-action? identityref grouping period-of-time: ... grouping recurrence: ... 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: ... Figure 2: Generic Schedule Configuration Tree Structure 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. Ma, et al. Expires 30 October 2024 [Page 5] Internet-Draft Common Schedule YANG April 2024 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. 3.2. The "period-of-time" Grouping The "period-of-time" grouping (Figure 3) represents a time period using either a start ("period-start") and end date and time ("period- end"), or a start ("period-start") and a positive time duration ("duration"). For the first format, the start of the period MUST be before the end of the period. Ma, et al. Expires 30 October 2024 [Page 6] Internet-Draft Common Schedule YANG April 2024 module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: +-- period-start? yang:date-and-time +-- time-zone-identifier? sys:timezone-name +-- (period-type)? +--:(explicit) | +-- period-end? yang:date-and-time +--:(duration) +-- duration? duration grouping recurrence: ... grouping recurrence-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: ... Figure 3: Period of Time Grouping Tree Structure 3.3. The "recurrence" Grouping The "recurrence" grouping (Figure 4) specifies a simple recurrence rule. Ma, et al. Expires 30 October 2024 [Page 7] Internet-Draft Common Schedule YANG April 2024 module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: +-- recurrence-first | +-- date-time-start? yang:date-and-time +-- frequency identityref +-- interval? uint32 +-- (recurrence-bound)? +--:(until) | +-- until? yang:date-and-time +--:(count) +-- count? 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: ... Figure 4: recurrence Grouping Tree Structure The "recurrence-first" container defines the first instance in the recurrence set, and the "date-time-start" specifies the date and time at which the first instance in the recurrence set occurs. 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. 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. Ma, et al. Expires 30 October 2024 [Page 8] Internet-Draft Common Schedule YANG April 2024 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.4. The "recurrence-utc" Grouping The "recurrence-utc" grouping (Figure 5) specifies a simple recurrence rule in UTC format. module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... grouping recurrence-utc: +-- recurrence-first | +-- date-time-start? yang:date-and-time | +-- duration? int32 +-- frequency identityref +-- interval? uint32 +-- (recurrence-bound)? +--:(until) | +-- until? yang:date-and-time +--:(count) +-- count? 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: ... Figure 5: recurrence-utc Grouping Tree Structure The "recurrence-utc" grouping refines the "recurrence" grouping to require that the date and time values to describe the recurrence be reported in UTC format. Ma, et al. Expires 30 October 2024 [Page 9] Internet-Draft Common Schedule YANG April 2024 It also augments the "recurrence-first" container with a parameter "duration" in units of seconds to allow the time period of the first occurrence to be specified. The "duration" also applies to subsequent recurrence instances. The "recurrence-utc" grouping is designed to be reused in scheduling contexts where machine readability is more desirable. 3.5. The "recurrence-with-time-zone" Grouping The "recurrence-with-time-zone" grouping (Figure 6) specifies a simple recurrence rule with a time zone. module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... grouping recurrence-utc: ... grouping recurrence-with-time-zone: +-- recurrence-first | +-- date-time-start? yang:date-and-time | +-- duration? duration | +-- time-zone-identifier? sys:timezone-name +-- frequency identityref +-- interval? uint32 +-- (recurrence-bound)? +--:(until) | +-- until? yang:date-and-time +--:(count) +-- count? uint32 grouping recurrence-utc-with-date-times: ... grouping recurrence-time-zone-with-date-times: ... grouping icalendar-recurrence: ... grouping schedule-status: ... Figure 6: recurrence-with-time-zone Grouping Tree Structure Ma, et al. Expires 30 October 2024 [Page 10] Internet-Draft Common Schedule YANG April 2024 The "recurrence-with-time-zone" grouping augments the "recurrence- first" container with the "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. It also augments the "recurrence-first" container with a parameter "duration" to allow the time period of the first occurrence to be specified. The "duration" also applies to subsequent recurrence instances. Unlike the definition of "recurrence-utc" grouping Section 3.4, "recurrence-with-time-zone" is intended to promote human readability over machine readability. 3.6. The "recurrence-utc-with-date-times" Grouping The "recurrence-utc-with-date-times" grouping (Figure 7) uses the "recurrence-utc" grouping (Section 3.4) and adds a "period-timeticks" list to define an aggregate set of repeating occurrences. Ma, et al. Expires 30 October 2024 [Page 11] Internet-Draft Common Schedule YANG April 2024 module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... grouping recurrence-utc: ... grouping recurrence-with-time-zone: ... grouping recurrence-utc-with-date-times: +-- recurrence-first | +-- date-time-start? yang:date-and-time | +-- duration? int32 +-- frequency identityref +-- interval? uint32 +-- (recurrence-bound)? | +--:(until) | | +-- until? yang:date-and-time | +--:(count) | +-- count? 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: ... Figure 7: recurrence-utc-with-date-times Grouping Tree Structure 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. 3.7. 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.5) and adds a "period" list to define an aggregate set of repeating occurrences. Ma, et al. Expires 30 October 2024 [Page 12] Internet-Draft Common Schedule YANG April 2024 module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... grouping recurrence-utc: ... grouping recurrence-with-time-zone: ... grouping recurrence-utc-with-date-times: ... grouping recurrence-time-zone-with-date-times: +-- recurrence-first | +-- date-time-start? yang:date-and-time | +-- duration? duration | +-- time-zone-identifier? sys:timezone-name +-- frequency identityref +-- interval? uint32 +-- (recurrence-bound)? | +--:(until) | | +-- until? yang:date-and-time | +--:(count) | +-- count? uint32 +-- period* [period-start] +-- period-start yang:date-and-time +-- time-zone-identifier? sys:timezone-name +-- (period-type)? +--:(explicit) | +-- period-end? yang:date-and-time +--:(duration) +-- duration? duration grouping icalendar-recurrence: ... grouping schedule-status: ... Figure 8: recurrence-time-zone-with-date-times Grouping Tree Structure The recurrence instances are specified by the union of occurrences defined by both the recurrence rule and "period" list. Duplicate instances are ignored. Ma, et al. Expires 30 October 2024 [Page 13] Internet-Draft Common Schedule YANG April 2024 3.8. The "icalendar-recurrence" Grouping The "icalendar-recurrence" grouping (Figure 9) uses the "recurrence- time-zone-with-date-times" grouping (Section 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]. module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... 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 | +-- date-time-start? yang:date-and-time | +-- duration? duration | +-- time-zone-identifier? sys:timezone-name +-- frequency identityref +-- interval? uint32 +-- (recurrence-bound)? | +--:(until) | | +-- until? yang:date-and-time | +--:(count) | +-- count? uint32 +-- 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 Ma, et al. Expires 30 October 2024 [Page 14] Internet-Draft Common Schedule YANG April 2024 +-- 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: ... Figure 9: icalendar-recurrence Grouping Tree Structure 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. Ma, et al. Expires 30 October 2024 [Page 15] Internet-Draft Common Schedule YANG April 2024 The "workweek-start" data node specifies the day on which the week starts. This is significant when a "weekly" recurrence rule has an interval greater than 1, and a "byday" data node is specified. This is also significant when in a "yearly" rule and a "byyearweek" is specified. The default value is "monday". The "exception-dates" data node specifies a list of exceptions for recurrence. The final recurrence set is generated by gathering all of the date and time values generated by any of the specified recurrence rule and date-times, and then excluding any start date and time values specified by "exception-dates" parameter. 3.9. The "schedule-status" Grouping The "schedule-status" grouping (Figure 10) defines common parameters for scheduling management/status exposure. module: ietf-schedule grouping generic-schedule-params: ... grouping period-of-time: ... grouping recurrence: ... 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: +-- schedule-id? string +-- state? identityref +-- version? uint16 +--ro schedule-type? identityref +--ro last-update? yang:date-and-time +--ro counter? uint32 +--ro last-occurrence? yang:date-and-time +--ro upcoming-occurrence? yang:date-and-time Figure 10: Schedule Status Grouping Tree Structure Ma, et al. Expires 30 October 2024 [Page 16] Internet-Draft Common Schedule YANG April 2024 The "schedule-id" parameter is useful to uniquely identify a schedule in a network device or controller if multiple scheduling contexts exists. The "state" parameter is defined to configure/expose the scheduling state, depending on the use of the grouping. The "identityref" type is used for this parameter to allow extensibility in future modules. For example, a "conflict" state is valid in scheduling contexts where multiple systems struggle for the scheduling of the same property. The conflict may be induced by, e.g., multiple entities managing the schedules for the same target component. The "version" parameter is used to track the current schedule version information. The version can be bumped by the entity who create the schedule. The "last-update" parameter identifies when the schedule was last modified. In some contexts, this parameter can be used to track the configuration of a given schedule. In such cases, the "version" may not be used. The "schedule-type" parameter identifies the type of the current schedule. The "counter", "last-occurrence", and "upcoming- occurrence" data nodes are only avaliable when the "schedule-type" is "recurrence". The current grouping captures common parameters that is applicable to typical scheduling contexts known so far. Future modules can define other useful parameters as needed. For example, in a scheduling context with multiple system sources to feed the schedules, the "source" and "precedence" parameters may be needed to reflect how schedules from different sources should be prioritised. 4. Features and Augmentations The "ietf-schedule" data model defines the recurrence related groupings using a modular approach. Basic, intermediate, and advanced representation of recurrence groupings are defined, with each reusing the previous one and adding more parameters. To allow for different options, two features are defined in the data model: * 'basic-recurrence-supported' * 'icalendar-recurrence-supported' Appendix B.1 provides an example about how that could be used. Implementations may support a basic recurrence rule or an advanced one as needed, by declaring different features. Whether only one or both features are supported is implementation specific and depend on specific scheduling context. Ma, et al. Expires 30 October 2024 [Page 17] Internet-Draft Common Schedule YANG April 2024 These groupings can also be augmented to support specific needs. As an example, Appendix B.2 demonstrates how additional parameters can be added to comply with specifc schedule needs. 5. Note and Restrictions There are some restrictions that need to be followed when using groupings defined in "ietf-schedule" yang module: * The instant in time represented by "period-start" MUST be before the "period-end" for "period-of-time" grouping * The combination of the day, month, and year represented for date and time value MUST be valid. See Section 5.7 of [RFC3339] for the maxinum day number based on the month and year. * The second MUST have the value "60" at the end of months in which a leap second occurs for date and time value * Care must be taken when defining recurrence occurring very often and frequent that can be an additional source of attacks by keeping the system permanently busy with the management of scheduling * Schedules received with a starting time in the past with respect to current time SHOULD be ignored 6. The "ietf-schedule" YANG Module This module imports types defined in [RFC6991]. file "ietf-schedule@2024-04-16.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; reference "RFC 6991: Common YANG Data Types"; } import ietf-system { prefix sys; reference "RFC 7317: A YANG Data Model for System Management"; } Ma, et al. Expires 30 October 2024 [Page 18] Internet-Draft Common Schedule YANG April 2024 organization "IETF NETMOD Working Group"; contact "WG Web: WG List: Editor: Qiufang Ma Editor: Mohamed Boucadair Author: Daniel King "; description "This YANG module defines a set of common 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-supported { description Ma, et al. Expires 30 October 2024 [Page 19] Internet-Draft Common Schedule YANG April 2024 "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; Ma, et al. Expires 30 October 2024 [Page 20] Internet-Draft Common Schedule YANG April 2024 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; Ma, et al. Expires 30 October 2024 [Page 21] Internet-Draft Common Schedule YANG April 2024 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 period { base schedule-type; description "Indicates a period based schedule."; } identity recurrence { base schedule-type; description "Indicates a recurrence based schedule."; } identity schedule-state { description "Base identity for schedule state."; } identity enabled { Ma, et al. Expires 30 October 2024 [Page 22] Internet-Draft Common Schedule YANG April 2024 base schedule-state; description "Indicates a recurrence with an enabled state."; } identity disabled { base schedule-state; description "Indicates a recurrence with a disabled state."; } identity out-of-date { base schedule-state; description "Indicates a recurrence with an out-of-date state."; } identity discard-action { description "Indicates that 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 "Incldues a set of generic configuration parameters that are followed by the entity that supports schedules. These parameters apply to all schedules. Such parameters are used as guards to prevent, e.g., stale configuration."; Ma, et al. Expires 30 October 2024 [Page 23] Internet-Draft Common Schedule YANG April 2024 leaf time-zone-identifier { type sys:timezone-name; description "Indicates the identifier for the time zone in a time zone database."; } leaf validity { type yang:date-and-time; description "Specifies the date and time after which a schedule will be considered as invalid. This paratemer takes precedence over similar attributes that are provided at the schedule instance itself."; } leaf max-allowed-start { type yang:date-and-time; description "Specifies the maximum scheduled start date and time, a requested schedule instance whose first occurrence after this value cannot be accepted by the entity. Specifically, a requested schedule will be rejected if the first occurrence of that new 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 instance whose first occurrence before this value cannot be accepted by the entity. Specifically, a requested schedule will be rejected if the first occurrence of that new 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."; Ma, et al. Expires 30 October 2024 [Page 24] Internet-Draft Common Schedule YANG April 2024 } } 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 { Ma, et al. Expires 30 October 2024 [Page 25] Internet-Draft Common Schedule YANG April 2024 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 yang:date-and-time; description "Defines the instant date and time of the first instance in the recurrence set."; } } leaf frequency { type identityref { base frequency-type; } mandatory true; 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. The default value is '1', means every second for a 'secondly' recurrence rule, every minute for a 'minutely' rule, and so on."; } choice recurrence-bound { description "Modes to bound the recurrence rule. If no choice is indicated, the recurrence rule is considered to repeat Ma, et al. Expires 30 October 2024 [Page 26] Internet-Draft Common Schedule YANG April 2024 forever."; case until { description "This case defines a way that bounds the recurrence rule in an inclusive manner."; leaf until { type yang:date-and-time; description "This parameter specifies a date and time value to bound 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 "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-utc { description "A simple definition of recurrence with time specified in UTC. This grouping is intended to be machine-friendly."; uses recurrence { refine "recurrence-first/date-time-start" { description "Defines the instant date and time of the first instance in the recurrence set. A UTC format MUST be used."; } refine "recurrence-bound/until" { description "This parameter specifies a date and time value to bound the recurrence. If the value specified by this parameter is synchronized with the specified recurrence, it becomes the last instance of the recurrence. A UTC format MUST be used."; } augment "recurrence-first" { Ma, et al. Expires 30 October 2024 [Page 27] Internet-Draft Common Schedule YANG April 2024 description "Adds a parameter indicating how long the occurrence lasts."; leaf duration { type int32; units "seconds"; description "When specified, it refers to the duration of each occurrence. The duration is in units of seconds. The exact duration also applies to all the recurrence instance."; } } } } grouping recurrence-with-time-zone { description "A simple definition of recurrence that allows the time to be specified with a local time and time zone. This grouping is intended to be human-friendly."; uses recurrence { augment "recurrence-first" { description "Adds parameters indicating how long the occurrence lasts and time zone identifier of the occurrence."; 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 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 'date-time-start' and/or 'until' value is neither reported in the format of UTC nor time zone offset to UTC."; } } } } grouping recurrence-utc-with-date-times { description Ma, et al. Expires 30 October 2024 [Page 28] Internet-Draft Common Schedule YANG April 2024 "This grouping defines an aggregate set of repeating occurrences with UTC time format. The recurrence instances are specified by the union of 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 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 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 union of occurrences defined by both the recurrence rule and 'period' Ma, et al. Expires 30 October 2024 [Page 29] Internet-Draft Common Schedule YANG April 2024 list. Duplicate instances are ignored."; uses recurrence-with-time-zone; 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-time-zone-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))"; Ma, et al. Expires 30 October 2024 [Page 30] Internet-Draft Common Schedule YANG April 2024 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 { Ma, et al. Expires 30 October 2024 [Page 31] Internet-Draft Common Schedule YANG April 2024 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 is defined to identify common properties of scheduling status."; leaf schedule-id { type string; description "The schedule identifier that globally identifies a schedule in a device, controller, network, etc. The unicity scope depends on the implementation."; } leaf state { type identityref { base schedule-state; } description "The current state of the schedule."; } leaf version { type uint16; description "The version number of the schedule."; } leaf schedule-type { type identityref { base schedule-type; } Ma, et al. Expires 30 October 2024 [Page 32] Internet-Draft Common Schedule YANG April 2024 config false; description "The schedule type."; } leaf last-update { type yang:date-and-time; config false; description "The timestamp that the schedule is last updated."; } leaf counter { when "derived-from-or-self(../schedule-type, " + "'schedule:recurrence')"; type uint32; config false; description "The counter of occurrences since the schedule was enabled. The count wraps around when it reaches the maximum value."; } leaf last-occurrence { when "derived-from-or-self(../schedule-type, " + "'schedule:recurrence')"; type yang:date-and-time; config false; description "The timestamp of last occurrence."; } leaf upcoming-occurrence { when "derived-from-or-self(../schedule-type, " + "'schedule:recurrence')" + "and derived-from-or-self(../state, 'schedule:enabled')"; type yang:date-and-time; config false; description "The timestamp of next occurrence."; } } } 7. Security Considerations This section uses the template described in Section 3.7 of [I-D.ietf-netmod-rfc8407bis]. The "ietf-schedule" YANG module specified in this document defines schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. Ma, et al. Expires 30 October 2024 [Page 33] Internet-Draft Common Schedule YANG April 2024 The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to- implement secure transport is TLS [RFC8446]. The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. The "ietf-schedule" module defines a set of types and groupings. These nodes are intended to be reused by other YANG modules. The module by itself does not expose any data nodes that are writable, data nodes that contain read-only state, or RPCs. As such, there are no additional security issues related to the "ietf- schedule" module that need to be considered. 8. IANA Considerations 8.1. The "IETF XML" Registry This document registers the following URI in the "IETF XML Registry" [RFC3688]. URI: urn:ietf:params:xml:ns:yang:ietf-schedule Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. 8.2. The "YANG Module Names" Registry This document registers the following YANG module in the "YANG Module Names" registry [RFC6020]. name: ietf-schedule namespace: urn:ietf:params:xml:ns:yang:ietf-schedule prefix: schedule maintained by IANA: N reference: RFC XXXX 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Ma, et al. Expires 30 October 2024 [Page 34] Internet-Draft Common Schedule YANG April 2024 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . Ma, et al. Expires 30 October 2024 [Page 35] Internet-Draft Common Schedule YANG April 2024 9.2. Informative References [I-D.contreras-opsawg-scheduling-oam-tests] Contreras, L. M. and V. Lopez, "A YANG Data Model for Network Diagnosis by scheduling sequences of OAM tests", Work in Progress, Internet-Draft, draft-contreras-opsawg- scheduling-oam-tests-01, 10 July 2023, . [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, 19 February 2021, . [I-D.ietf-netmod-rfc8407bis] Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", Work in Progress, Internet-Draft, draft-ietf- netmod-rfc8407bis-11, 18 April 2024, . [I-D.ietf-opsawg-ucl-acl] Ma, Q., Wu, Q., Boucadair, M., and D. King, "A YANG Data Model and RADIUS Extension for Policy-based Network Access Control", Work in Progress, Internet-Draft, draft-ietf- opsawg-ucl-acl-03, 2 February 2024, . [I-D.ietf-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-ietf-tvr-schedule-yang- 00, 16 April 2024, . [I-D.ietf-tvr-use-cases] Birrane, E. J., Kuhn, N., Qu, Y., Taylor, R., and L. Zhang, "TVR (Time-Variant Routing) Use Cases", Work in Progress, Internet-Draft, draft-ietf-tvr-use-cases-09, 29 February 2024, . Ma, et al. Expires 30 October 2024 [Page 36] Internet-Draft Common Schedule YANG April 2024 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . 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 "generic-schedule-params" Grouping Figure 11 indicates 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. { "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" } Figure 11: Generic Parameters for Schedule Validation A.2. 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 12. { "period-start": "2025-01-01T08:00:00Z", "period-end": "2027-12-31T18:00:00Z" } Figure 12: Simple Start/End Schedule Ma, et al. Expires 30 October 2024 [Page 37] Internet-Draft Common Schedule YANG April 2024 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 13. { "period-start": "2025-01-01T08:00:00Z", "duration": "P15DT05:20:00" } Figure 13: 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 14. { "period-start": "2025-11-19T02:00:00", "time-zone-identifier": "America/Los_Angeles", "duration": "P20W" } Figure 14: Simple Schedule with Time Zone Indication A.3. The "recurrence" Grouping Figure 17 indicates a recurrence of every 2 days for 10 occurrences, starting at 3 p.m. on December 1, 2025 with an offset of -8:00 from UTC: { "recurrence-first": { "date-time-start": "2025-12-01T15:00:00-08:00:00" }, "frequency": "ietf-schedule:daily", "interval": 2, "count": 10 } Figure 15: Simple Schedule with Recurrence A.4. The "recurrence-utc" Grouping Figure 16 indicates a recurrence from 8:00 AM to 9:00 AM every day, from December 1 to December 31, 2025 in UTC: Ma, et al. Expires 30 October 2024 [Page 38] Internet-Draft Common Schedule YANG April 2024 { "recurrence-first": { "date-time-start": "2025-12-01T08:00:00Z", "duration": 3600; }, "frequency": "ietf-schedule:daily", "interval": 1, "until": "2025-12-31T23:59:59Z" } Figure 16: Simple Schedule with Recurrence in UTC A.5. The "recurrence-with-time-zone" Grouping Figure 17 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: { "recurrence-first": { "date-time-start": "2025-12-01T15:00:00", "duration": "PT00:10:00", "time-zone-identifier": "America/New_York" }, "frequency": "ietf-schedule:hourly", "interval": 2, "count": 10 } Figure 17: Simple Schedule with Recurrence with Time Zone Indication A.6. The "recurrence-utc-with-date-times" Grouping Figure 18 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: Ma, et al. Expires 30 October 2024 [Page 39] Internet-Draft Common Schedule YANG April 2024 { "recurrence-first": { "date-time-start": "2025-06-01T09:00:00Z", }, "frequency": "ietf-schedule:daily", "interval": 2, "until": "2025-06-30T23:59:59Z", "period-timeticks": [ { "period-start": "3240000", "period-end": "3420000" }, { "period-start": "5400000", "period-end": "5640000" } ] } Figure 18: Example of Recurrence With Date Times A.7. The "recurrence-time-zone-with-date-times" Grouping Figure 19 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): { "recurrence-first": { "date-time-start": "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" } ] } Ma, et al. Expires 30 October 2024 [Page 40] Internet-Draft Common Schedule YANG April 2024 Figure 19: Example of Advanced Recurrence Schedule A.8. The "icalendar-recurrence" Grouping Figure 20 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 20: Simple iCalendar Recurrence Figure 21 is an example of a recurrence that occurs on the last workday of the month until December 25, 2025, from January 1, 2025: { "recurrence-first": { "date-time-start": "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 21: Example of Advanced iCalendar Recurrence Figure 22 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: Ma, et al. Expires 30 October 2024 [Page 41] Internet-Draft Common Schedule YANG April 2024 { "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 22: Example of Advanced iCalendar Recurrence with Exceptions A.9. The "schedule-status" Grouping Figure 23 indicates the scheduled recurrence status of Figure 22 at the time of 12:15 PM, 2025-12-01 (UTC): { "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"] } Figure 23: Example of a Schedule Status 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. Appendix B. Examples of Using/Extending the "ietf-schedule" Module This non-normative section shows two examples for how the "ietf- schedule" module can be used or extended for scheduled events or attributes based on date and time. B.1. Example: Schedule Tasks to Execute Based on a Recurrence Rule Scheduled tasks can be used to execute specific actions based on certain recurrence rules (e.g., every Friday at 8:00 AM). The following example module which "uses" the "icalendar-recurrence" grouping from "ietf-schedule" module shows how a scheduled task could be defined with different features used for options. Ma, et al. Expires 30 October 2024 [Page 42] Internet-Draft Common Schedule YANG April 2024 module example-scheduled-backup { yang-version 1.1; namespace "http://example.com/example-scheduled-backup"; prefix "ex-scback"; import ietf-inet-types { prefix "inet"; } import ietf-schedule { prefix "schedule"; } organization "Example, Inc."; contact "Support at example.com"; description "Example of a module defining an scheduled based backup operation."; revision "2023-01-19" { description "Initial Version."; reference "RFC XXXX: A YANG Data Model for Scheduling."; } container scheduled-backup-tasks { description "A container for backing up all current running configuration on the device."; list tasks { key "task-id"; description "The list of backing up tasks on this device."; leaf task-id { type string; description "The task identifier that uniquely identifies a scheduled backup task."; } choice local-or-remote { description "Specifies whether the configuration to be backed up is local or remote."; Ma, et al. Expires 30 October 2024 [Page 43] Internet-Draft Common Schedule YANG April 2024 case local { description "Configuration parameters for backing up of local devices."; leaf local { type empty; description "The parameter specifies the configuration to be backed up is on the local device."; } } case remote { description "Configuration parameters for backing up of remote devices."; leaf remote { type inet:domain-name; description "The parameter specifies the remote device domain name."; } } } container basic-recurrence-schedules { if-feature schedule:basic-recurrence-supported; description "Basic recurrence schedule specification, only applies when schedule:basic-recurrence-supported feaure is supported."; leaf schedule-id { type string; description "The schedule identifier for this recurrence rule."; } uses schedule:recurrence; } container icalendar-recurrence-schedules { if-feature schedule:icalendar-recurrence-supported; description "Basic recurrence schedule specification, only applies when schedule:icalendar-recurrence-supported feaure is supported."; leaf schedule-id { type string; description "The schedule identifier for this recurrence rule."; } Ma, et al. Expires 30 October 2024 [Page 44] Internet-Draft Common Schedule YANG April 2024 uses schedule:icalendar-recurrence; } } list schedule-set { key "schedule-id"; description "The list of schedule status for the backup tasks."; uses schedule:schedule-status; } } } B.2. Example: Schedule Network Properties to Change Based on Date and Time Network properties may change over a specific period of time or based on a recurrence rule, e.g., [I-D.ietf-tvr-use-cases]. The following example module which augments the "recurrence-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."; Ma, et al. Expires 30 October 2024 [Page 45] Internet-Draft Common Schedule YANG April 2024 revision "2023-01-19" { description "Initial Version."; reference "RFC XXXX: A YANG Data Model for Scheduling."; } grouping link-bandwidth-grouping { description "Grouping of the link bandwidth definition."; leaf scheduled-bandwidth { type uint64; units "Kbps"; description "Bandwidth values, expressed in kilobits per second."; } } container link-attributes { description "Definition of link attributes."; list link { key "source-node destination-node"; description "Definition of link attributes."; leaf source-node { type nw:node-id; description "Indicates the source node identifier."; } leaf destination-node { type nw:node-id; description "Indicates the source node identifier."; } leaf default-bandwidth { type uint64; units "Kbps"; description "Default bandwidth values when unspecified."; } choice time-variant-type { description "Controls the schedule type."; case period { uses schedule:period-of-time; Ma, et al. Expires 30 October 2024 [Page 46] Internet-Draft Common Schedule YANG April 2024 } 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 24 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. ne1 ne2 1000 2025-12-01T01:00:00Z schedule:daily 2025-12-31T23:59:59Z 360000 2160000 500 7920000 8280000 800 Ma, et al. Expires 30 October 2024 [Page 47] Internet-Draft Common Schedule YANG April 2024 Figure 24: 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, Joe Clarke, 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. Authors' Addresses Qiufang Ma (editor) Huawei 101 Software Avenue, Yuhua District Jiangsu 210012 China Email: maqiufang1@huawei.com Qin Wu Huawei 101 Software Avenue, Yuhua District Jiangsu 210012 China Email: bill.wu@huawei.com Mohamed Boucadair (editor) Orange 35000 Rennes France Email: mohamed.boucadair@orange.com Daniel King Lancaster University United Kingdom Email: d.king@lancaster.ac.uk Ma, et al. Expires 30 October 2024 [Page 48]