Adding Schedules

[ldodds]

A quick proposal based on discussion in #240.

Schema.org doesn't currently have a way to express recurring events.

While it will always be useful to share data on individual instances, e.g. the event happening this Tuesday at 6pm. There are also scenarios where it is useful to be able to share a general rule, e.g. this event happens at 6pm every Tuesday.

Use cases include sharing data about physical activities, e.g. regular gym classes or similar events.

iCalendar already refines a model and terms for expressing recurring events. And this
is independently supported in libraries like rrecurjs. We could draw on this to define a similar model for schema.org

The proposal is to define a new schedule property, a EventSchedule type and some additional properties for describing the schedule.

The schedule property will be associated with Events. It will allow the description of a schedule, expressed as a recurrence rule for describing the frequency of upcoming events.

The EventSchedule type will have properties based on those in iCalendar. But in the below, the naming has been aligned with existing schema.org properties.

• startTime - the existing property, date/time at which the schedule starts
• endTime - existing property, date/time at which the schedule ends
• frequency - "daily", "monthly", "yearly"
• day - DayOfWeek
• month - month of the year
• hour - hour
• minute - minute
• count - optionally specfiy the number of recurring events
• exceptionRule - repeating property, specifies date-times when the schedule doesn't apply, equivalent to exrule in ical

I think this covers the core aspects of a schedule. I may have missed something essential (am not an iCal expert) but I think this type of rule will cover many use cases so worth considering.

This structure can be easily expressed in, e.g. JSON-LD, but may be trickier in RDFa. I've not tried that yet, but wanted to float this for discussion.

[magico]

Hi ldodds,

Thanks for putting this together. I had some comments on your proposal:

• startTime: if you’re referring to the date when the schedule starts then startDate may be more appropiate
• endTime: as above. May be worth mentioning that if no endDate is specified then it’s assumed the event has been scheduled indefinitely
• frequency: what’s the expected type here? An easy way may be to specify a number, so it knows how many to skip
• day: a distinction between DayOfWeek (e.g. to create a schedule on every Monday) and DayOfMonth (a new type) may be useful.
• hour & minute: I would use startTime and endTime instead, both with Time as the expected type
• count: because we’re already specifying startDate, endDate, and the frequency, I am not sure we need count as it can be calculated.

As mentioned above, DayOfMonth would be a new type that would have 1 to 31 as possibilities (http://schema.org/1, http://schema.org/2, http://schema.org/3, etc)

Also, I would change the names around so eventSchedule is the property from Event and Schedule is the new type.

I’ve put together some examples of how it may work with different schedules:

Every 3rd Monday from 9am to 10am

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": “3",
      "day": "http://schema.org/Monday",
      “startTime": "09:00",
      “endTime": "10:00"
    }
}
</script>

Every 1st and 15th of every month from 9am to 10am

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "1",
      "day": [{"http://schema.org/1"},{"http://schema.org/15"}]
      “startTime": "09:00",
      “endTime": "10:00"
    }
}
</script>

Every working day of the week twice, from 9am to 10am and then from 2pm to 3pm

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    [
     {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "1",
      "day": [{"http://schema.org/Monday"},{"http://schema.org/Tuesday"},{"http://schema.org/Wednesday"},{"http://schema.org/Thursday"},{"http://schema.org/Friday"}]
      “startTime": "09:00",
      “endTime": "10:00"
     },
     {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "1",
      "day": [{"http://schema.org/Monday"},{"http://schema.org/Tuesday"},{"http://schema.org/Wednesday"},{"http://schema.org/Thursday"},{"http://schema.org/Friday"}]
      “startTime": “14:00",
      “endTime": “15:00"
     }
    ]
}
</script>

Thoughts?

[ldodds]

Hi,

• Specifying both start/end dates and time as you suggest seems reasonable to me
• I'm fine either way with DayOfWeek or DayOfMonth. My reason for going with DayOfWeek is simply that it exists already and I was aiming for smallest set of changes.
• replacing hour and minute with start/endTime also seems reasonable. Follows my above rule better or trying to use fewer properties. I specified several here to match iCalendar. I think its worth considering whether alignment with iCal is a good thing to preserve.
• Agree that count can be calculated, but I don't see any harm in specifying exactly how many events will run. E.g. starting tomorrow we'll run 10 weekly events

I'm not convinced by changing daily/weekly/monthly frequency indicators for numbers though. Specifying the unit seems clear to me.

[danbri]

This all looks pretty sensible. Any thoughts on how it relates to our existing (two!) mechanisms for opening hours?

[magico]

I'm not convinced by changing daily/weekly/monthly frequency indicators for numbers though. Specifying the unit seems clear to me.

@ldodds The only reason I suggested numbers as frequency indicators is because I didn't think the daily/weekly/monthly indicators would work as well with schedules such as "every 3 mondays". Happy to be proved wrong though.

[ldodds]

I'll post an updated proposal here in next few days or so incorporating comments. @danbri I'll also highlight overlaps with opening hours.

[rdebourbon]

This looks pretty good. My only lingering queries would be:

1. Should the frequency be a ISO 8601 representation rather than an integer? This allows for the frequency to specified in various units including time components as appropriate. In the first example, it would be P3W (3 weeks), in the second (P1M), and in the third (P1W).
2. Do we need to include actual duration and have some notion of setup / tear down time. I know at the moment, we're primarily looking at this from the customer opportunity side, where the setup/tear down time is of little consequence, but when it comes to determining availability, those blocks of time become very critical and do need to be factored in.
3. High frequency activities - eg Golf. Typically, golf as an activity has a long duration, but is defined with a high frequency, low duration because the expected time spent at each hole is relatively short. In this instance, we tend to have see recurrence rules that specifies every N minutes between XX:XX and YY:YY on A/B/C/D/E days. I realise that this can be easily handled as per the last example with multiple days and times - I just have lingering queries about "potential bloat" in the data required to represent such a "common" schedule.

[danbri]

ping @ldodds - any updates?

[magico]

Should the frequency be a ISO 8601 representation rather than an integer? This allows for the frequency to specified in various units including time components as appropriate. In the first example, it would be P3W (3 weeks), in the second (P1M), and in the third (P1W).

This makes sense. +1

[ldodds]

Revised Proposal

THIS IS THE LATEST VERSION OF THE PROPOSAL.

I've left the original proposal and discussion intact above, but will revise this comment in line with ongoing discussion. Please add comments below.

Goal

Provide a means to define scheduled events. The primary use case is to describe schedules for things like:

• Meetups, e.g. a monthly tech meetup or business networking event
• Gym classes or similar opportunities to be active

The goal isn't to offer the full flexibility of iCalendar, so the features described here are a subset of iCalendars recurrence rules. Alignment with iCalendar is preserved where possible. It's a tried and tested model.

Summary of Proposed Changes

• Add new Schedule type for describing schedules
• Add new eventSchedule property to associate an Event to a Schedule. The value can be an array to allow for definition of several schedules.
• Add several new properties (see below) to help describe a Schedule

eventSchedule

Generally speaking it is preferable to publish data about individual events, but this isn't always helpful. For example it may be more useful to
publish and share a schedule rather than an endless set of web pages.

The eventSchedule property associates a Schedule with an Event.

The property can be specified instead of a specific start and end time to indicate that the event occurs on a regular basis. All other aspects of
a recurring event, e.g. its description, location, etc can be captured using existing properties.

The value of the eventSchedule property can be a single Schedule or an array of Schedule instance to allow for multiple schedules to
be specified.

Schedule

Schedules draw on the trade and tested approach defined in iCalendar. So, in line with iCalendar we need to specify

1. the period during which the schedule is active
2. the rule to use to decide when the next event(s) will take place
3. any exceptions to the rule that can be used to indicate that an event won't take place. Broadly equivalent to iCalendar exrule.

We can specify the period when an Schedule is active using existing properties:

• startDate - Date or DateTime that the schedule starts, not the event
• endDate - Date or DateTime that the schedule starts

Instead of specifying an endDate we might instead want to specify how many events will take place:

• count - optionally specfiy the number of recurring events. positive integer

We can describe the rule for generating events using some additional new properties:

• frequency - one of a fixed set of values: "hourly", "daily", "weekly", "monthly", "yearly"

• interval - how often the events occur. a positive integer

• byDay - day of the week. refers to a [DayOfWeek](https://schema.org/DayOfWeek)

• byMonthDay - day of the month. positive integer, 1-31

• byMonth - month of the year, 1-12

We can define exception using a new property:

• exceptDate - value is a Date or DateTime value, or an array of such values, that specifiy when an event won't take place. Can be repeated to describe multiple exception.

Some iCalendar features that are not supported:

• Specifying higher frequency events, e.g. byMinute or byHour
• No way to define events that occur on specific week numbers (e.g. 3rd week in the year) or year days (Day 100)
• Modifiers on rule values, e.g. so can't express "Last Monday of the Month"
• No bySetPos support
• rdate, e.g. listing individual dates when an event will occur. In Schema.org we can handle this by specifying multiple events or repeating date/date-time properties
• exceptRule, e.g. defining a rule to capture exceptions

Useful icalendar references on rrule and recur.

Worked Examples

Using those proposed by @magicomartinez

Every 3rd Monday from 9am to 10am

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "weekly",
      "byDay": "http://schema.org/Monday",
      "interval": 3,
      "startTime": "09:00",
      "endTime": "10:00"
    }
}
</script>

The 1st and 15th of every month from 9am to 10am

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "monthly",
      "byMonthDay": [1, 15],
      “startTime": "09:00",
      “endTime": "10:00"
    }
}
</script>

Starting daily from 24th December, between 9am-10am for 10 occurances

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "frequency": "daily",
      "count": 10,
      “startTime": "09:00",
      “endTime": "10:00"
    }
}
</script>

Every other day, from 24th December 2016, forever

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    {
      "@type": "Schedule",
      "startDate": "2016-12-24"
      "frequency": "daily",
      "interval": 2,
      “startTime": "09:00",
      “endTime": "10:00"
    }
}
</script>

Every working day of the week twice, from 9am to 10am and then from 2pm to 3pm

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "Example",
  "eventSchedule":
    [
     {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "daily",
      "byDay": ["http://schema.org/Monday","http://schema.org/Tuesday","http://schema.org/Wednesday","http://schema.org/Thursday","http://schema.org/Friday"]
      “startTime": "09:00",
      “endTime": "10:00"
     },
     {
      "@type": "Schedule",
      "startDate": "2016-12-24",
      "endDate": "2017-12-25",
      "frequency": "daily",
      "byDay": ["http://schema.org/Monday","http://schema.org/Tuesday","http://schema.org/Wednesday","http://schema.org/Thursday","http://schema.org/Friday"]
      “startTime": “14:00",
      “endTime": “15:00"
     }
    ]
}
</script>

[ldodds]

@rdebourbon @magicomartinez I'm not sure it makes sense to specify frequency using the duration support in ISO 8601. Is there a reason to prefer that over the (revised) specification.

@rdebourbon also there's already the duration property of an event. That could be specified on the Event rather than the schedule as normal.

For setup/teardown, that might be something we need to consider as part of OpenActive as it doesn't necessarily apply to Schema.org's more general Event support?

[rdebourbon]

@ldodds - My rationale around specifying it in something other than an integer was to avoid any potential confusion / misinterpretation around the original frequency as an integer. An ISO 8601 duration string also effectively combines frequency and interval into a single standard well described type.

@ldodds - The duration of an event can vary at the session level. In fact, experience has taught me that quite a few properties typically defined at the event level can vary at the session level (eg location). An example of varying duration though is often encountered when defining schedules for peak / off peak periods - which again can have different recurrence rules. Eg Peak period sessions are 30minutes long every 30minutes between XX:XX and YY:YY on days F,Sa. Off peak they are 60minutes every 120minutes between AA:AA and BB:BB on days M,W,F. Noticing that Friday occurs in both peak & off-peak so needs complimentary recurrence rules defined depending on the actual dates involved.

[jamiefoale]

Hi guys,

Is there a way we can include a provision for bank holidays? Theres a big inconsistency between venues about whether they are / aren't open and I know many recurring activities are not held on bank holidays, but some are.

It doesnt seem like it is on Schema.org but Im thinking something along the lines of
“bankHoliday": "yes"

Thanks

[nickmhalliday]

From an entirely non technical perspective - how do the proposals above - or whatever we incline towards get piloted or tested with some users? There is a bit of a risk in putting lots of work into features / formats that are not used and that we miss others that will be found useful. No doubt you have an approach to this already that I am not aware of.....