Merge pull request #45 from netmod-wg/reshad-review

Reshard-review

draft-ietf-netmod-schedule-yang.md

@@ -59,8 +59,8 @@ informative:
    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.
+   the module includes a set of recurrence related groupings with varying granularity levels
+   (i.e., from basic to advanced).
 
 --- middle
 
@@ -119,12 +119,12 @@ System:
 ##  Features {#sec-features}
 
    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.
+   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-supported"
-   *  "icalendar-recurrence-supported"
+   *  "basic-recurrence"
+   *  "icalendar-recurrence"
 
    Refer to {{sec-aug}} for the use of these features.
 
@@ -147,7 +147,7 @@ System:
 
    * "generic-schedule-params" ({{sec-gen}})
    * "period-of-time" ({{sec-period}})
-   * "recurrence" ({{sec-rec}})
+   * "recurrence-basic" ({{sec-rec}})
    * "recurrence-utc" ({{sec-rec-utc}})
    * "recurrence-with-time-zone" ({{sec-rec-tz}})
    * "recurrence-utc-with-date-times" ({{sec-rec-utc-dt}})
@@ -220,9 +220,9 @@ System:
 ~~~~
 {: #pt-tree title="Period of Time Grouping Tree Structure"}
 
-### The "recurrence" Grouping {#sec-rec}
+### The "recurrence-basic" Grouping {#sec-rec}
 
-  The "recurrence" grouping ({{rec-grp-tree}}) specifies a simple recurrence rule.
+  The "recurrence-basic" grouping ({{rec-grp-tree}}) specifies a simple recurrence rule.
 
 ~~~~
 {::include ./yang/tree/rec-grp.txt}
@@ -243,15 +243,15 @@ System:
 
 ### The "recurrence-utc" Grouping {#sec-rec-utc}
 
-   The "recurrence-utc" grouping ({{rec-utc-grp-tree}}) uses the "recurrence"
+   The "recurrence-utc" grouping ({{rec-utc-grp-tree}}) uses the "recurrence-basic"
    grouping and specifies a simple recurrence rule in UTC format.
 
 ~~~~
 {::include ./yang/tree/rec-utc-grp.txt}
 ~~~~
 {: #rec-utc-grp-tree title="recurrence-utc Grouping Tree Structure"}
 
-   The "utc-start-time" indicates the start time in UTC format.
+   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.
 
@@ -260,7 +260,7 @@ The interval specifies when a schedule will occur, combined with the frequency p
 an occurence will last.
 
   The repetition can be scoped by a specified end time or by a count of occurrences,
-  indicated by the "recurrence-bound" choice. The "utc-start-time" value always counts
+  indicated by the "recurrence-bound" choice. The "start-time-utc" value always counts
   as the first occurrence.
 
    The "recurrence-utc" grouping is designed to be reused in scheduling contexts
@@ -269,22 +269,22 @@ an occurence will last.
 ### The "recurrence-with-time-zone" Grouping {#sec-rec-tz}
 
    The "recurrence-with-time-zone" grouping ({{rec-tz-grp-tree}}) uses the
-   "recurrence" grouping and specifies a simple recurrence rule with a time zone.
+   "recurrence-basic" grouping and specifies a simple recurrence rule with a time zone.
 
 ~~~~
 {::include ./yang/tree/rec-tz-grp.txt}
 ~~~~
 {: #rec-tz-grp-tree title="recurrence-with-time-zone Grouping Tree Structure"}
 
-   The "recurrence-first" container includes "date-time-start" and "duration" parameters
+   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-bound" choice. The "date-time-start" value always counts
+  indicated by the "recurrence-bound" choice. The "start-time" value always counts
   as the first occurrence.
 
    Unlike the definition of "recurrence-utc" grouping ({{sec-rec-utc}}),
@@ -542,16 +542,20 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 # Examples of Format Representation {#usage}
 
    This section provides some examples to illustrate the use of the
-   period and recurrence formats defined in {{sec-schedule}}. Note that a "grouping"
-   does not define any data nodes in the schema tree; the examples illustrated are
-   thus for the ease of understanding. Only the message body is provided with
+   period and recurrence formats defined in {{sec-schedule}}.
+
+   Note that a "grouping" does not define any data nodes in the schema tree;
+   the examples illustrated are thus for the ease of understanding.
+
+   For each example, only the message body is provided with
    JSON used for encoding per the guidance in {{?RFC7951}}.
 
 ## The "generic-schedule-params" Grouping
 
-   {{ex-0}} indicates the example of a requested schedule that needs to start no earlier than
+   {{ex-0}} 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.
+   Schedule requests that fail to meet the requirements are ignored by the system as indicates by
+   "discard-action".
 
 ~~~~
 {
@@ -599,7 +603,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {: #ex-3 title="Simple Schedule with Time Zone Indication"}
 
-## The "recurrence" Grouping
+## The "recurrence-basic" Grouping
 
    {{ex-6}} indicates a recurrence of every 2 days which starts immediately and repeat forever:
 
@@ -620,7 +624,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-    "utc-start-time": "2025-12-01T08:00:00Z",
+    "start-time-utc": "2025-12-01T08:00:00Z",
     "duration": 3600;
   },
   "frequency": "ietf-schedule:daily",
@@ -638,7 +642,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-    "date-time-start": "2025-12-01T15:00:00",
+    "start-time": "2025-12-01T15:00:00",
     "duration": "PT00:10:00",
     "time-zone-identifier": "America/New_York"
   },
@@ -658,7 +662,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-    "utc-start-time": "2025-06-01T09:00:00Z",
+    "start-time-utc": "2025-06-01T09:00:00Z",
   },
   "frequency": "ietf-schedule:daily",
   "interval": 2,
@@ -686,7 +690,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-    "date-time-start": "2025-12-01T09:00:00",
+    "start-time": "2025-12-01T09:00:00",
     "duration": "PT00:15:00",
     "time-zone-identifier": "America/New_York"
   },
@@ -715,7 +719,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-    "date-time-start": "2024-01-27T08:00:00",
+    "start-time": "2024-01-27T08:00:00",
     "time-zone-identifier": "America/New_York"
   },
   "frequency": "ietf-schedule:monthly",
@@ -736,7 +740,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-  "date-time-start": "2025-01-01"
+  "start-time": "2025-01-01"
   },
   "frequency": "ietf-schedule:monthly",
   "until": "2025-12-25",
@@ -759,7 +763,7 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
 ~~~~
 {
   "recurrence-first": {
-    "date-time-start": "2025-12-01T09:00:00Z"
+    "start-time": "2025-12-01T09:00:00Z"
   },
   "until": "2025-12-01T16:40:00Z",
   "frequency": "ietf-schedule:minutely",
@@ -868,3 +872,5 @@ This section uses the template described in {{Section 3.7 of ?I-D.ietf-netmod-rf
    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.

yang/example-scheduled-backup.yang

@@ -71,24 +71,23 @@ module example-scheduled-backup {
       }
 
       container basic-recurrence-schedules {
-        if-feature schedule:basic-recurrence-supported;
+        if-feature schedule:basic-recurrence;
         description
           "Basic recurrence schedule specification, only applies when
-           schedule:basic-recurrence-supported feaure is supported.";
+           schedule:basic-recurrence feaure is supported.";
         leaf schedule-id {
           type string;
           description
             "The schedule identifier for this recurrence rule.";
         }            
-        uses schedule:recurrence;
+        uses schedule:recurrence-basic;
        }
 
       container icalendar-recurrence-schedules {
-        if-feature schedule:icalendar-recurrence-supported;
+        if-feature schedule:icalendar-recurrence;
         description
           "Basic recurrence schedule specification, only applies when
-           schedule:icalendar-recurrence-supported feaure is
-           supported.";
+           schedule:icalendar-recurrence feaure is supported.";
         leaf schedule-id {
           type string;
           description

yang/ietf-schedule.yang

@@ -61,13 +61,13 @@ module ietf-schedule {
       "RFC XXXX: A Common YANG Data Model for Scheduling";
   }
 
-  feature basic-recurrence-supported {
+  feature basic-recurrence {
     description
       "Indicates that the server supports configuring a basic
        scheduled recurrence.";
   }
 
-  feature icalendar-recurrence-supported {
+  feature icalendar-recurrence {
     description
       "Indicates that the server supports configuring a comprehensive
        scheduled icalendar recurrence";
@@ -401,7 +401,7 @@ module ietf-schedule {
     }
   }
 
-  grouping recurrence {
+  grouping recurrence-basic {
     description
       "A simple definition of recurrence.";
     leaf recurrence-description {
@@ -436,7 +436,7 @@ module ietf-schedule {
     container recurrence-first {
       description
         "Specifies the first instance of the recurrence.";
-      leaf utc-start-time {
+      leaf start-time-utc {
         type yang:date-and-time;
         description
           "Defines the instant date and time of the first instance
@@ -482,7 +482,7 @@ module ietf-schedule {
         }
       }
     }
-    uses recurrence;
+    uses recurrence-basic;
   }
 
   grouping recurrence-with-time-zone {
@@ -493,7 +493,7 @@ module ietf-schedule {
     container recurrence-first {
       description
         "Specifies the first instance of the recurrence.";
-      leaf date-time-start {
+      leaf start-time {
         type yang:date-and-time;
         description
           "Defines the instant date and time of the first instance 
@@ -512,9 +512,8 @@ module ietf-schedule {
         description
           "Indicates the identifier for the time zone in a time
            zone database. This parameter MUST be specified if
-           'date-time-start' or 'until' value is neither
-           reported in the format of UTC nor time zone offset to
-           UTC.";
+           'start-time' or 'until' value is neither reported in
+           the format of UTC nor time zone offset to UTC.";
       }
     }
     choice recurrence-bound {
@@ -547,7 +546,7 @@ module ietf-schedule {
         }
       }
     }
-    uses recurrence;
+    uses recurrence-basic;
   }
 
   grouping recurrence-utc-with-date-times {

yang/tree/ical-grp.txt

@@ -4,7 +4,7 @@ module: ietf-schedule
     ...
   grouping period-of-time:
     ...
-  grouping recurrence:
+  grouping recurrence-basic:
     ...
   grouping recurrence-utc:
     ...
@@ -16,7 +16,7 @@ module: ietf-schedule
     ...
   grouping icalendar-recurrence:
     +-- recurrence-first
-    |  +-- date-time-start?        yang:date-and-time
+    |  +-- start-time?             yang:date-and-time
     |  +-- duration?               duration
     |  +-- time-zone-identifier?   sys:timezone-name
     +-- (recurrence-bound)?

yang/tree/overall.txt

@@ -4,7 +4,7 @@ module: ietf-schedule
     ...
   grouping period-of-time:
     ...
-  grouping recurrence:
+  grouping recurrence-basic:
     ...
   grouping recurrence-utc:
     ...

yang/tree/period-grp.txt

@@ -11,7 +11,7 @@ module: ietf-schedule
        |  +-- period-end?       yang:date-and-time
        +--:(duration)
           +-- duration?         duration
-  grouping recurrence:
+  grouping recurrence-basic:
     ...
   grouping recurrence-utc:
     ...

yang/tree/rec-grp.txt

@@ -4,7 +4,7 @@ module: ietf-schedule
     ...
   grouping period-of-time:
     ...
-  grouping recurrence:
+  grouping recurrence-basic:
     +-- recurrence-description?   string
     +-- frequency                 identityref
     +-- interval?                 uint32

yang/tree/rec-tz-dt-grp.txt

@@ -4,7 +4,7 @@ module: ietf-schedule
     ...
   grouping period-of-time:
     ...
-  grouping recurrence:
+  grouping recurrence-basic:
     ...
   grouping recurrence-utc:
     ...
@@ -14,7 +14,7 @@ module: ietf-schedule
     ...
   grouping recurrence-time-zone-with-date-times:
     +-- recurrence-first
-    |  +-- date-time-start?        yang:date-and-time
+    |  +-- start-time?             yang:date-and-time
     |  +-- duration?               duration
     |  +-- time-zone-identifier?   sys:timezone-name
     +-- (recurrence-bound)?

yang/tree/rec-tz-grp.txt

@@ -4,13 +4,13 @@ module: ietf-schedule
     ...
   grouping period-of-time:
     ...
-  grouping recurrence:
+  grouping recurrence-basic:
     ...
   grouping recurrence-utc:
     ...
   grouping recurrence-with-time-zone:
     +-- recurrence-first
-    |  +-- date-time-start?        yang:date-and-time
+    |  +-- start-time?             yang:date-and-time
     |  +-- duration?               duration
     |  +-- time-zone-identifier?   sys:timezone-name
     +-- (recurrence-bound)?