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.....

[rdebourbon]

@jamiefoale I would expect that Bank Holidays and other closures would be handled via an "exceptDate" array of values. This allows for greatest flexibility from an underlying data structure. If we include a "bankHoliday" attribute we then potentially need to clarify how a particular data source determines bank holidays. In this instance a more generic exception list is probably easiest for everyone involved.

Having said that, @ldodds, would it be a good idea to allow for an optional reason text for the exception so that venues / operators can distinguish between expected closures and unexpected changes to the schedule?

[nickevansuk]

Great point @rdebourbon around cancellation, I wonder if that question can be framed even more broadly:

Assuming we have a recurrence rule in place, how do we associate additional property values to a particular occurance. Examples include:

• One occurance has moved to a different venue (most likely exceptDate on current event + a new event with different property values?)
• One occurance has been cancelled (could be same as previous, with a new event with property of cancelled and the reason provided)
• We want to specify the availability of each occurance, i.e number of spaces left (would this require separate events for each occurrence, would such events require all the properties filled out?).

What this leads me to wonder is whether there's a parent-child model where the "master" event specifies a number of properties including a recurrence rule, and "override" events are provided in an array similar to exceptDate, but with an array of type Event. Each Event would inherit the properties of the master, and only include additional properties required (such as "cancelled" and "cancellation reason", or "location", or simply an "available spaces" integer).

This would potentially reduce the size of data payload required to cater for e.g. Recurring sessions which include availability.

[ldodds]

Catching up here, most of the follow-up comments relate to how to add extra information to specific instances of an event (e.g. why cancelled, or change of location). I think that can already be accommodated by the existing superEvent/subEvent properties.

For example I can associate a specific instance of an Event (which might have changed duration and venue) with the schedule by a superEvent property. This indicates that the Event is part of the broader series. I'd expect an application to rely on specific properties of that instance in favour of those specified on the parent (basically inheritance/override).

But I think that's outside the scope of specifying a simple set of recurrence rules. And some of this is specific to OpenActive rather than a more general Schema.org mechanism.

@danbri what do we need to do to move this forward? I'm trying to decide whether to:

• move all of this into out OpenActive specification and namespace document, and later define equivalence with Schema.org if there's consensus
• push this forward so we can rely on it and drop the caveats on our own spec.

I'd prefer the latter :)

[ldodds]

@danbri @rvguha I'm looking to move the OpenActive specification a step forward through the W3C community group process. The only major area that currently has a caveat is the handling of recurring events. As I noted in my previous comment, I've got two options, either define our own mechanism or progress this proposal.

I'd prefer to keep alignment with Schema.org as we've been doing that elsewhere for the core model.

What's the likelihood of getting my proposal here, which seems to have reasonable support, accepted into Schema.org? Is there anything I can do to help move that forward?

[danbri]

I would be happy to have this in schema.org, so long as we figure out how it relates in expressivity and scope to our two(!) existing opening hour mechanisms. Many many interesting events, and associated changes of state (beyond opening/closing of availability) happen on schedules, not least for devices (see iot.schema.org). It feels like some kind of test cases repo might be useful for documenting clearly the meaning of complex schedule and opening hours data..m

[ldodds]

@danbri just to confirm, the 2 mechanism you're referrring to are openingHours and OpeningHoursSpecification. Want to make sure I'm focusing on the right things before clarifying overlap. I'll note that neither of those address our use case, but agree its worth describing the overlap.

Also, re: test repo would a public github repo with JSON-LD examples we enough, or were you thinking of something else? If there's an example of how you've done this for other proposals that would be great.

[ldodds]

Comparison with Opening Hours Mechanisms

As requested by @danbri How does this proposal relate to the two existing mechanisms that Schema.org has for describing "opening hours"?

openingHours

The openingHours property is a text property that is used on LocalBusiness and CivicStructure types. Ranges are encoded as structured text with abbreviated English language day names.

The property is focused on a specific use case of describing opening hours for businesses. It can be used to describe opening and closing times for a single day, separate days or ranges of days.

It's unable to express more complex schedules, e.g. weekly or monthly, but these would be quite unusual for businesses anyway.

It also doesn't treat the period when a shop is open as an Event. The property allows a client to easily calculate whether a point of interest is currently open or closed (or will be over the next few days).

The property is used on a large number of domains (more than OpeningHoursSpecification) but I think its been around for longer than the second approach.

OpeningHoursSpecification

The OpeningHoursSpecification is a newer approach to capturing opening hours in Schema.org.

It allows opening hours to be specified for the Service, ContactPoint and Place properties. So it can be applied to a broader domain than openingHours.

While the Schema.org documentation for LocalBusiness still uses openingHours, the Google Developer documentation recommends use of this type and its properties instead. It's presumably therefore preferred over the original form, at least by Google.

It captures the same basic information, but models the opening hours in a more structured way, e.g.:

• uses URIs (DayOfWeek) for days, instead of abbreviated string literals
• uses Time instance to express time as XML Schema times
• can specify opening times between a set of calendar dates, and not just days of the week. E.g. for seasonal opening hours

Other than adding structure and the ability to describe different opening hours based on calendar dates, it captures essentially the same information. But obviously in a more structured and better documented way.

Again, it doesn't express opening hours as Events and doesn't deal with other frequencies of schedules.

Discussion

The existing mechanisms focus on a specific use case that, as defined, doesn't overlap with the schedule proposal here which is explicitly aimed to support scheduling of Events.

We've found that systems already capture schedules using iCal, so providing a limited way to express this in Schema.org would be a step forward.

For the OpenActive project, it would be useful to capture opening times for the venues, e.g. Leisure Centres at which events might take place. But in this case we'll likely recommend that people use OpeningHoursSpecification as it currently fulfils a different need and its supported in search engines.

It would be possible to express opening hours as a schedule instead, e.g.:

{
 "@type": "Place",
 "openingHoursSchedule": {
    "@type": "Schedule"
    "frequency": "daily",
    "interval": 1,
    "startTime": "09:00",
    "endTime": "17:00"
  }
}

We can see how the OpeningHoursSpecification and proposed Schedule types compare:

Schedule	OpeningHoursSpecification
startTime	opens
endTime	closes
startDate	validFrom
endDate	validThrough
count	-
frequency	-
interval	-
byDay	dayOfWeek
byMonthDay	-
byMonth	-
exceptDate	-

The meaning of dayOfWeek and byDay are not quite the same but are close.

It should be possible to express any OpeningHoursSpecification as a Schedule but not vice versa.
OpeningHoursSpecification could be seen as a specialisation of Schedule that supports a specific use
case.

Schedule because it's grounded in iCal provides a better foundation for capturing other scheduling information than OpeningHoursSpecification.

OpeningHoursSpecification and its predecessor are designed to better support adding structured data to existing opening hours text on websites, whereas Schedule information is more likely to come from automated systems and calendaring type applications.

Data could be directly exchanged as iCal schedules, e.g. via an rrule, but this approach avoids all clients having to implement full iCal support and supports use cases where schedules are presented to users.

In terms of encouraging alignment and rationalisation it might be better to:

• public deprecate openingHours in favour of OpeningHoursSpecification (outside the scope of this proposal)
• consider formally defining OpeningHoursSpecification as a sub-class of Schedule and defining some alignment between properties

@danbri does that help? :)

[thadguidry]

@ldodds I like your Schedule. For me it works. But...Hmm... it seems that iCal has acknowledged a few gaps in their modeling over the years and are trying to fill those in.

Will Schedule have a "location" property also ? Because it seems that iCal is trying for an approach where Schedule itself can have a Location property. Your case with OpenActive is approaching against an Event (which already has Location property) and then saying the Event has a Schedule. Referencing https://icalendar.org/RFC-Specifications/iCalendar-Venue-Draft/ and all the new properties forthcoming https://icalendar.org/RFC-Specifications/all/

Is there anything for or against also having a location property under Schedule as in the iCal Venue Draft above ?

Example that iCal Venue Draft proposal is saying :

• Event has a Schedule

• Schedule has a Location

[ldodds]

@thadguidry I wasn't aware of that. I should be clear that I'm not aiming for a complete import of ical into schema.org so haven't look at achieving a complete mapping, or looked at any proposed enhancements.

However, I'm not sure it makes sense to add a location field for the Schedule I've been outlining here. A brief look at the example from the ical venue draft suggests that it is VEVENT which is equivalent to Event, not the recurrence rules. So their location proposal is really just improving something that Schema.org already handles via its location property.

The proposal here is essentially to map ical rrule into Schema.org. So extending Schema.org Event with a structure that VEVENT already allows.

[thadguidry]

@ldodds Thanks. And I completely agree, an Event is at a location... not a Schedule :) We got things right in Schema.org and iCal is just catching up :) Just wanted to point that out for all for posterity sake and in case anyone comes back to this asking silly questions. (That proposal affords a VVENUE btw, which we already have)

[danbri]

@ldodds

the 2 mechanism you're referrring to are openingHours and OpeningHoursSpecification.
Yes.

For testcases, I am not entirely sure what the right structure is. @gkellogg and friends have done a lot around RDF testing. For this case the idea would be something like:

1. Collect a bunch of usecases
2. Have a concrete file (in JSON-LD or ntriples or whatever - the triples being the important bit) using openingHours and/or OpeningHoursSpecification in some stereotypical or exotic / cornercase manner.
3. Have a question recorded somewhere in some simple format indicating a point in time or a period.
4. The "answer" is whether the thing is "open" at that time, or "closed" or some other list we'd enumerate (e.g. at a point time it is transitioning from open to closed or vice versa).

There would be some nuance around cornercases like open all day, closed all day, times spanning midnight, broadening to schedules, mixing the two idioms for opening hours in one description, dealing with defaults and missing information and so on.

[ldodds]

@danbri am still not quite sure what you're asking in terms of shaping up this proposal.

As it stands schedule and the 2 opening hours mechanisms are really separate features, although clearly both are about specifying time periods in some form.

Rationalising the two opening hours mechanisms is a separate issue I think. Am not sure resolving that legacy decision should block this proposal?

Or are you also suggesting that we also need to broaden this proposal schedule to make it work for opening hours too, before it'll be considered further? That's possible as I've outlined above, but could also be done as a separate exercise?

I may be confused by your examples which are all about opening hours. I'd originally assumed you just wanted better documentation and examples to back up the schedule proposal.

[danbri]

@ldodds they are indeed separable. I am just wary of having three partially-equivalent mechanisms for specifying time periods. Even if "opening hours" was not fragmented, we ought to at least understand the extent to which the schedule proposal differed.

The test case idea is essentially a sketch of a way of mapping out this expressivity so we know what we've done, and whether e.g. one is a strict superset of the other's.

[ldodds]

@danbri does the analysis I posted above, with the property breakdown not cover that already? Opening hours seems pretty limited in scope to me.

I'm very happy to put together some more examples of using schedule and opening hours, but am wary about committing to building a testing framework where none exists.

[ldodds]

@chaals OK. I'll use repeatFrequency as I had same thought and @danbri has previously suggested its better to qualify properties to avoid clashes.

I'll define it as covering both domains and will specify frequency as a super property for now.

[ldodds]

I've submitted PR #1693 to cover moving this to pending. Can I suggest that any further suggestions on naming, etc are added as comments on specific changes there?

[nickevansuk]

To throw something else in here: should we also include "duration" in the schedule? Currently this is defined in http://schema.org/Event, but would it make more sense to include it in the schedule along with the start and end times?

• It would help with repeated events that span multiple days (you could use duration instead of endTime).
• It would allow an array of schedules to be included for an event, where the schedules have varying durations.

[peter-dolkens]

I think that duration would be good as an inherited property from Event, so that if it differs from the Event duration, it can be included in Schedule to override it, but isn't normally required there.

[nickevansuk]

Also have we factored in the "every 2nd Thursday of every two months" scenario here: openactive/implementation-tracker#6 (comment)

[ldodds]

@nickevansuk @dolkensp what use cases do we have for specifying duration? Some concrete examples would be useful. Duration can be derived from start/endTime so can be calculated, so really looking for examples of where a publisher couldn't just specify an end time. It looks like a simple change, but we'll need to be clear that what is being specified isn't the duration of a schedule (it has its own start/end times) and also avoid any confusion about having 2 properties both of which contain a ISO 8601 duration.

@nickevansuk I've not considered the "every 2nd Thursday of every two months" scenario, largely to focus on getting the core properties in place. To make that change the byDay property would need to accept both DayOfWeek and Text values (using iCal format, e.g. 2TH). The alternative is to define it in a more structured way. We'd probably have to take the same approach with the other properties too.

This raises questions of how much of iCal to import (there are other "byX") properties and also complexity in working out the interplay between ISO 8601 durations and those properties.

Anyone else have thoughts on that?

Btw, I'm keen to get a basic proposal into pending (ref earlier PR) to capture what agreement we've been able to get to date, before extending further if possible.

[thadguidry]

@ldodds You'll want to add duration. I agree for some of the same reasons that @nickevansuk gives. Sometimes folks just don't state the end time on even repeated events. Even cool calendar apps automatically calculate the endtime for you when you type or slide in the duration. "My meeting starts in 1 hour and I'll be tied up for 2 hours everyday this week....sorry, can't give more advice, gotta run" :) That's a use case for Google Home and Alexa.

[peter-dolkens]

@thadguidry

even cool calendar apps automatically calculate the endtime for you when you type or slide in the duration

I think @ldodds's point was that given a start time, and a duration, we should be able to calculate the end time anyways.

I'm inclined to keep both properties, as having the duration alone may be useful for some activities which take a fixed amount of time, but may be started at ANY time (private classes, etc)

[nickevansuk]

@ldodds in terms of duration, this is to allow the schedule to be expressed using either duration or endDate, and for it to explicitly override the duration in the parent event. In addition to the use cases above, using duration in the parent event when all other time-related properties live in the (potentially multiple) schedules seems inconsistent.

In terms of iCal, we must be aware that many implementations will be mapping from iCal, so we need to be clear on the equivalence. Using a byDay property that accepts both DayOfWeek and iCal Text values (using iCal format, e.g. 2TH) makes sense to me, as we want to use as much of schema.org as possible while not reinventing the wheel when existing standards exist. Potentially referencing iCal text values is akin to using UN/CEFACT common codes (http://schema.org/unitCode).

Given we're likely to want to have as much consistency as possible with Schema.org, but also mirror iCal's feature set, it looks like moving ahead with getting this into Schema.org pending asap would be a good step.

[danbri]

Regarding "duration" - I expect there are cornercases (e.g. daylight saving time changes) when computing the duration requires background knowledge or a supporting library. Being close to iCal would be good (and we can ask that community for a sanity check too).

[danbri]

Ok this is published now at schema.org (as 'pending', which means we want more review, discussion, implementor feedback e.g. w.r.t. mappings to ical, how to integrate with opening hours at least cross-referencing documentation, possible applicability in iot.schema.org, etc etc.).

https://schema.org/docs/releases.html#g1457

Let's leave this issue open to continue the discussion! Thanks Leigh et al for getting us to this milestone :)

[EdB2]

Here's hoping repeatCount and exceptDate won't be required. My purpose is 12-step recovery group meetings. These are not the type of schedule that has an end date (that we know of anyway). We say "Friday at 6PM" with an understanding that it will be every Friday (no exceptDate) forever (no repeatCount). For real-world context, once when the church we were in burned down we held our meeting in the parking lot until we could find a new home. The Schedule was kept, the Location eventually changed :)

BTW just wrapping my tired old brain around this stuff. Way cool ... but dynamically calling all the meetings for the next week as "Events" seems silly ... so thanks much for the work y'all have done towards make a Schedule a thing :)

[thadguidry]

@EdB2 Everything is optional in Schema.org technically, its consumers of the data that place restrictions where they see fit.

Ah, interesting use case with 12-step recovery groups ! Also, I see that use case as similar to perhaps a curriculum at a college where there's a final completion event of graduation after proceeding through all the courses (step 12 - "Carrying the message of the 12 Steps to others in need" is basically, "using the knowledge", just as students typically do after graduation.

@danbri Perhaps this also brings about the need for a narrower type "CourseSchedule" based on evidence in issues:
#195 - Course, CourseInstance, EducationEvent [Schema.org Course Extension]
#930 - Request for suitable classes/properties to represent "school term"
#1497 - Course Vocab add attribute to define expected time to take course

? dunno, but something we should investigate more within those 3.

[ldodds]

@danbri can I suggest we close this issue? The original proposal is now part of pending. Further iteration can happen in separate issues?

Can I ask what the process is for pending to move to live?

[nickevansuk]

Sorry just to pick up as I noticed this was closed, two things to raise:

duration and byDay

Can I pick up on the above ( #1457 (comment))

I notice that there is broad support and agreement in this thread for:

1. duration being part of Schedule
2. byDay accepting iCal format, e.g. "2TH"

But neither of these seem to have made it through to pending (and both are useful, e.g. see openactive/modelling-opportunity-data#2 (comment)).

Timezone

One further issue we are starting to see with implementors creating significant errors: the current Schedule proposal does not include timezone.

1. When does this Monday night class happen? 7pm during the summer and winter? 7pm what timezone?

  "eventSchedule": {
    "type": "Schedule",
    "repeatFrequency": "P1W"
    "byDay": "http://schema.org/Monday",
    "startTime": "19:00",
    "endTime": "20:00",
  }

2. When does this Monday night class happen? 7pm in the winter and 8pm in the summer during daylight savings?

  "eventSchedule": {
    "type": "Schedule",
    "repeatFrequency": "P1W"
    "byDay": "http://schema.org/Monday",
    "startTime": "19:00Z",
    "endTime": "20:00Z",
  }

[djodjoni]

I'm not sure if this is the correct place but I also noticed a couple of few other things.

There are some inconsistencies in the https://pending.schema.org/Schedule specs and examples as well as with the original proposal here.

1. We have startTime/endTime missing, which could be represented as a Duration and I assume this is the reason why "eventSchedule" property is in there.
   However, the documentation of it and the examples doesn't match.
   On the other hand we have those mentioned in the release notes https://schema.org/docs/releases.html#g1457
   What's the idea there?

2. startDate/endDate for the validity of the Schedule (not the Event duration), are also missing. what's the idea here?

I also have a suggestion for exceptDate to accept Duration as a value, as in my case I need to express a period of holidays there.

[peter-dolkens]

From the documentation: An Event <https://pending.schema.org/Event> that is associated with a Schedule <https://pending.schema.org/Schedule> using this property should not have startDate <https://pending.schema.org/startDate>or endDate <https://pending.schema.org/endDate> properties. These are instead defined within the associatedSchedule <https://pending.schema.org/Schedule> This would suggest to me that at the very least, the start date/time properties are currently missing from Schedule documentation. From previous comments in this thread, it would seem that StartTime/EndTime are expected to be available, and I would expect StartDate/EndDate to be available too. The documentation should also clarify if *Duration* is the duration of a single event, or if it's the duration of the entire schedule. I'm assuming the former.

…

On Sat, Sep 1, 2018 at 8:40 AM, Kalin Maldzhanski ***@***.***> wrote: I'm not sure if this is the correct place but I also noticed a couple of few other things. There are some inconsistencies in the https://pending.schema.org/Schedule specs and examples as well as with the original proposal here. 1. We have startTime/endTime missing, which could be represented as a Duration and I assume this is the reason why "eventSchedule" property is in there. However, the documentation of it and the examples doesn't match. On the other hand we have those mentioned in the release notes https://schema.org/docs/releases.html#g1457 <https://schema.org/docs/releases.html#g1457> What's the idea there? 2. startDate/endDate for the validity of the Schedule (not the Event duration), are also missing. what's the idea here? I also have a suggestion for exceptDate to accept Duration as a value, as in my case I need to express a period of holidays there. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1457 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAcqoojt2rupdv14jMT58jKLdd94wVe_ks5uWjn4gaJpZM4LNG0Z> .

[danbri]

@ldodds can you help us with updating the spec if needed, and any evidence of adoption - especially consuming applications that use rather than just publish this vocabulary?

[GeertThijs]

I have some questions:

• Am I correct that Schedule is only useful if the event is repeating? Meaning that for a non-repeating event you use Event.startDate to document the beginning of the Event and for a repeating Event Schedule.startDate should be used?
• Is the documentation of eventSchedule correct? It seems now that it is an attribute of Schedule, rather than an attribute of Event. The latter is suggested in the definition and in the examples. Meaning that eventSchedule should be added to Event and its range should not be Duration but Schedule.
• Wouldn't it be better to adapt the definition of Schedule so that it can be used also as an attribute of things that are not Event's. Eg for a service or a public transit line and such. Especially (as suggested earlier in this discussion) if you plan to make OpeninghoursSpecification a subclass of Schedule.

[ldodds]

@danbri I'm going to defer to @thill-odi who is leading the specification work on OpenActive and can give you concrete examples.

A quick look at the current docs suggest that they aren't correct. They should mention start/end Time and Date.

Basically, I'd expect Schema.org to be reflecting most, if not all of the recommended approach that we have in the OpenActive documentation:

https://www.openactive.io/modelling-opportunity-data/#publishing-event-schedules

OpenActive will likely have its own conformance criteria but I was hoping that the core Schedule model could end up in Schema.org.

I notice that the id/url template stuff is also not yet in Schema.org. I think that's useful on consumer side.

[DamonHD]

Did I miss something? (Likely!)

Is there any way yet of specifying the last Tuesday of every month? (Guess who has been asked to manage such an event and would now like to put up a page for with with correct metadata?)

Is it byDay = "-1TU" and repeatFrequency= "P1M"?

Rgds

Damon