365 - schedule validation

package.json

@@ -28,10 +28,13 @@
     "axios": "^0.19.2",
     "currency-codes": "^1.5.1",
     "html-entities": "^1.3.1",
+    "iso8601-duration": "^1.3.0",
     "jsonpath": "^1.0.2",
+    "luxon": "^1.26.0",
     "lodash": "^4.17.21",
     "moment": "^2.24.0",
-    "rrule": "^2.6.2",
+    "moment-timezone": "^0.5.33",
+    "rrule": "2.6.4",
     "striptags": "^3.1.1",
     "uritemplate": "^0.3.4",
     "validator": "^10.11.0",

src/errors/validation-error-type.js

@@ -40,6 +40,9 @@ const ValidationErrorType = {
   WRONG_BASE_TYPE: 'wrong_base_type',
   FIELD_NOT_ALLOWED: 'field_not_allowed',
   BELOW_MIN_VALUE_INCLUSIVE: 'below_min_value_inclusive',
+  URI_TEMPLATE_MISSING_PLACEHOLDER: 'uri_template_missing_placeholder',
+  EXCEPTION_DATES_NOT_IN_SCHEDULE: 'exception_dates_not_in_schedule',
+  INVALID_SCHEDULE_EVENT_TYPE: 'invalid_schedule_event_type',
   VALUE_OUTWITH_CONSTRAINT: 'value_outwith_constraint',
   INVALID_ID: 'invalid_id',
   FIELD_MUST_BE_ID_REFERENCE: 'FIELD_MUST_BE_ID_REFERENCE',

src/helpers/datetime-helper.js

@@ -0,0 +1,13 @@
+const { DateTime } = require('luxon');
+
+function getDateTime(ianaTimezone, dateString, timeString) {
+  // Node pulls the timezone from the system on initialisation using the TZ environment variable.
+  // We can change process.env.TZ to UTC. This will update the current Node process.
+  process.env.TZ = 'UTC';
+  if (typeof dateString !== 'undefined' && typeof timeString !== 'undefined') {
+    return DateTime.fromISO(`${dateString}T${timeString}`, { zone: ianaTimezone }).toJSDate();
+  }
+  return undefined;
+}
+
+module.exports = getDateTime;

src/helpers/frequency-converter.js

@@ -0,0 +1,27 @@
+const { parse } = require('iso8601-duration');
+const { RRule } = require('rrule');
+
+function getFrequency(repeatFrequency) {
+  if (typeof repeatFrequency !== 'undefined') {
+    const frequency = parse(repeatFrequency);
+
+    if (frequency.hours !== 0) {
+      return { freq: RRule.HOURLY, interval: frequency.hours };
+    }
+    if (frequency.days !== 0) {
+      return { freq: RRule.DAILY, interval: frequency.days };
+    }
+    if (frequency.weeks !== 0) {
+      return { freq: RRule.WEEKLY, interval: frequency.weeks };
+    }
+    if (frequency.months !== 0) {
+      return { freq: RRule.MONTHLY, interval: frequency.months };
+    }
+    if (frequency.years !== 0) {
+      return { freq: RRule.YEARLY, interval: frequency.years };
+    }
+  }
+  return { freq: undefined, interval: 0 };
+}
+
+module.exports = getFrequency;

src/helpers/rrule-options.js

@@ -0,0 +1,39 @@
+const getDateTime = require('./datetime-helper');
+
+function generateRRuleOptions(properties) {
+  const dtStart = getDateTime('UTC', properties.startDate, properties.startTime);
+  const dtEnd = getDateTime('UTC', properties.endDate, properties.endTime);
+
+  const rruleOptions = {};
+
+  if (typeof properties.freq !== 'undefined') {
+    rruleOptions.freq = properties.freq;
+  }
+  if (typeof properties.interval !== 'undefined') {
+    rruleOptions.interval = properties.interval;
+  }
+  if (typeof dtStart !== 'undefined') {
+    rruleOptions.dtstart = dtStart;
+  }
+  if (typeof dtEnd !== 'undefined') {
+    rruleOptions.until = dtEnd;
+  }
+  if (typeof properties.byDay !== 'undefined') {
+    rruleOptions.byweekday = properties.byDay;
+  }
+  if (typeof properties.byMonth !== 'undefined') {
+    rruleOptions.bymonth = properties.byMonth;
+  }
+  if (typeof properties.byMonthDay !== 'undefined') {
+    rruleOptions.bymonthday = properties.byMonthDay;
+  }
+  if (typeof properties.count !== 'undefined') {
+    rruleOptions.count = properties.count;
+  }
+  if (typeof properties.scheduleTimezone !== 'undefined') {
+    rruleOptions.tzid = properties.scheduleTimezone;
+  }
+  return rruleOptions;
+}
+
+module.exports = generateRRuleOptions;

src/helpers/schedule-properties.js

@@ -0,0 +1,22 @@
+const getFrequency = require('./frequency-converter');
+
+function getScheduleProperties(node) {
+  const { freq, interval } = getFrequency(node.getValue('repeatFrequency'));
+  const properties = {
+    freq,
+    interval,
+    byDay: node.getValue('byDay'),
+    byMonth: node.getValue('byMonth'),
+    byMonthDay: node.getValue('byMonthDay'),
+    startDate: node.getValue('startDate'),
+    startTime: node.getValue('startTime'),
+    endDate: node.getValue('endDate'),
+    endTime: node.getValue('endTime'),
+    count: node.getValue('count'),
+    scheduleTimezone: node.getValue('scheduleTimezone'),
+    exceptDate: node.getValue('exceptDate'),
+  };
+  return properties;
+}
+
+module.exports = getScheduleProperties;

src/rules/data-quality/schedule-contains-recurrence-data-rule-spec.js

@@ -0,0 +1,131 @@
+const ValidRecurrenceRule = require('./schedule-contains-recurrence-data-rule');
+const Model = require('../../classes/model');
+const ModelNode = require('../../classes/model-node');
+const ValidationErrorType = require('../../errors/validation-error-type');
+const ValidationErrorSeverity = require('../../errors/validation-error-severity');
+
+describe('ValidRecurrenceRule', () => {
+  const rule = new ValidRecurrenceRule();
+  const model = new Model({
+    type: 'Schedule',
+    fields: {
+      repeatFrequency: {
+        fieldname: 'byDay',
+        requiredType: 'https://schema.org/Duration',
+      },
+      byDay: {
+        fieldname: 'byDay',
+        requiredType: 'ArrayOf#https://schema.org/DayOfWeek',
+        alternativeTypes: ['ArrayOf#https://schema.org/Text'],
+      },
+      byMonth: {
+        fieldname: 'byMonth',
+        requiredType: 'https://schema.org/Integer',
+      },
+      byMonthDay: {
+        fieldname: 'byMonthDay',
+        requiredType: 'https://schema.org/Integer',
+      },
+      startDate: {
+        fieldname: 'startDate',
+        requiredType: 'https://schema.org/Date',
+      },
+      EndDate: {
+        fieldname: 'EndDate',
+        requiredType: 'https://schema.org/Date',
+      },
+      startTime: {
+        fieldname: 'startTime',
+        requiredType: 'https://schema.org/Time',
+      },
+      EndTime: {
+        fieldname: 'EndTime',
+        requiredType: 'https://schema.org/Time',
+      },
+      count: {
+        fieldname: 'count',
+        requiredType: 'https://schema.org/Integer',
+      },
+      scheduleTimezone: {
+        fieldName: 'scheduleTimezone',
+        requiredType: 'https://schema.org/Text',
+      },
+    },
+  }, 'latest');
+
+  it('should target Schedule models', () => {
+    const isTargeted = rule.isModelTargeted(model);
+    expect(isTargeted).toBe(true);
+  });
+
+  it('should return errors when startDate is missing', async () => {
+    const data = {
+      '@type': 'Schedule',
+      startTime: '08:30',
+      endTime: '09:30',
+      scheduleTimezone: 'Europe/London',
+    };
+
+    const nodeToTest = new ModelNode(
+      '$',
+      data,
+      null,
+      model,
+    );
+
+    const errors = await rule.validate(nodeToTest);
+
+    expect(errors.length).toBe(2);
+    for (const error of errors) {
+      expect(error.type).toBe(ValidationErrorType.MISSING_REQUIRED_FIELD);
+      expect(error.severity).toBe(ValidationErrorSeverity.FAILURE);
+    }
+  });
+
+  it('should return errors when startTime is missing', async () => {
+    const data = {
+      '@type': 'Schedule',
+      startDate: '2021-03-19',
+      repeatFrequency: 'P1W',
+      count: 1,
+      scheduleTimezone: 'Europe/London',
+    };
+
+    const nodeToTest = new ModelNode(
+      '$',
+      data,
+      null,
+      model,
+    );
+
+    const errors = await rule.validate(nodeToTest);
+
+    expect(errors.length).toBe(2);
+    for (const error of errors) {
+      expect(error.type).toBe(ValidationErrorType.MISSING_REQUIRED_FIELD);
+      expect(error.severity).toBe(ValidationErrorSeverity.FAILURE);
+    }
+  });
+
+  it('should not return errors when there are sufficent properties to build a valid recurrence rule', async () => {
+    const data = {
+      '@type': 'Schedule',
+      startDate: '2021-03-19',
+      startTime: '08:30',
+      repeatFrequency: 'P1W',
+      count: 1,
+      scheduleTimezone: 'Europe/London',
+    };
+
+    const nodeToTest = new ModelNode(
+      '$',
+      data,
+      null,
+      model,
+    );
+
+    const errors = await rule.validate(nodeToTest);
+
+    expect(errors.length).toBe(0);
+  });
+});

src/rules/data-quality/schedule-contains-recurrence-data-rule.js

@@ -0,0 +1,94 @@
+const { RRule } = require('rrule');
+const Rule = require('../rule');
+const generateRRuleOptions = require('../../helpers/rrule-options');
+const getScheduleProperties = require('../../helpers/schedule-properties');
+const ValidationErrorType = require('../../errors/validation-error-type');
+const ValidationErrorCategory = require('../../errors/validation-error-category');
+const ValidationErrorSeverity = require('../../errors/validation-error-severity');
+
+module.exports = class ValidRecurrenceRule extends Rule {
+  constructor(options) {
+    super(options);
+    this.targetModels = ['Schedule'];
+    this.meta = {
+      name: 'ValidRecurrenceRule',
+      description:
+        'Validates that the Schedule contains the correct information to generate a valid iCal recurrence rule.',
+      tests: {
+        matchingFirstEvent: {
+          message:
+          'The first event that is generated by the `Schedule` ({{firstEvent}}) does not match the `startDate` ({{startDate}}) and `startTime` ({{startTime}}).',
+          sampleValues: {
+            startTime: '08:30',
+            startDate: '2021-03-19',
+            firstEvent: '2021-03-20T09:40:00Z',
+          },
+          category: ValidationErrorCategory.CONFORMANCE,
+          severity: ValidationErrorSeverity.FAILURE,
+          type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+        },
+        rruleCreation: {
+          message:
+          'There was an error generating the RRule from the data provided. Error: {{error}}',
+          category: ValidationErrorCategory.CONFORMANCE,
+          severity: ValidationErrorSeverity.FAILURE,
+          type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+        },
+        dtStart: {
+          message:
+            'The recurrence rule must contain a `startDate`, `startTime`, and `scheduledTimezone` to generate the schedule.',
+          sampleValues: {
+            startTime: '08:30',
+            startDate: '2021-03-19',
+            scheduleTimezone: 'Europe/London',
+          },
+          category: ValidationErrorCategory.CONFORMANCE,
+          severity: ValidationErrorSeverity.FAILURE,
+          type: ValidationErrorType.MISSING_REQUIRED_FIELD,
+        },
+      },
+    };
+  }
+
+  validateModel(node) {
+    const errors = [];
+
+    const properties = getScheduleProperties(node);
+    const rruleOptions = generateRRuleOptions(properties);
+
+    if (typeof properties.startDate === 'undefined'
+        || typeof properties.startTime === 'undefined'
+        || typeof properties.scheduleTimezone === 'undefined') {
+      errors.push(
+        this.createError('dtStart', {
+          value: undefined,
+          path: node,
+        }),
+      );
+    }
+
+    try {
+      const rule = new RRule(rruleOptions);
+      const firstEvent = rule.all()[0];
+      if (firstEvent.getTime() !== rruleOptions.dtstart.getTime()) {
+        errors.push(
+          this.createError('matchingFirstEvent', {
+            startDate: properties.startDate,
+            startTime: properties.startTime,
+            firstEvent,
+            path: node,
+          }),
+        );
+      }
+    } catch (error) {
+      errors.push(
+        this.createError('rruleCreation', {
+          error,
+          path: node,
+        }),
+      );
+    }
+
+    return errors;
+  }
+};