Proposal: Restrict startDate/endDate to only occur in subEvent items

[lukehesluke]

Proposer

imin (https://www.imin.co/)

Proposal

• Currently .startDate and .endDate are allowed in the root level of an Event as well as in a subEvent
• Further to the proposal to restrict usage of properties to increase consistency (https://github.com/openactive/modelling-opportunity-data/issues/78), this should be limited to just the subEvent
• Because there is a possibility of multiple subEvent items, it is required to at least be available for those objects. A single subEvent item is identical to the use case of having an Event with no subEvent specified making that case redundant

Use Case

Consistency makes integration simpler for developers, testers, etc

Why is this not covered by existing properties?

The existing properties are insufficiently simple

Please provide a link to example data

• GLL's feed (https://www.better.org.uk/odi/sessions.json) has .startDate and .endDate in the Event and no data in .subEvent field
• Fusion's feed (https://fusion-lifestyle-openactive.azurewebsites.net/api/sessions) has Events with .subEvent field, each of which has either one or more items

Example

• Old world:

  {
  "type": "Event",
  "url": "https://better.org.uk/leisure-centre/queen-elizabeth-olympic-park/copper-box-arena/timetable",
  "name": "Total Body Conditioning",
  "startDate": "2018-07-05T20:30:00Z",
  "endDate": "2018-07-05T21:30:00Z",
  // no "subEvent"
  // ...and all the rest of the fields
  }

• New world:

  {
  "type": "Event",
  "url": "https://better.org.uk/leisure-centre/queen-elizabeth-olympic-park/copper-box-arena/timetable",
  "name": "Total Body Conditioning",
  // no "startDate" or "endDate"
  "subEvent": [{
    "type": "Event",
    "startDate": "2018-07-05T20:30:00Z",
    "endDate": "2018-07-05T21:30:00Z",
  }],
  // ...and all the rest of the fields
  }

[nickevansuk]

+1 this makes sense to me.

Also assume remainingAttendeeCapacity and maximumAttendeeCapacity would only be at subEvent level?

[nickevansuk]

Just checked a few of the feeds, and I don't think we've never used more than one level of subEvent. So suggest we just make one level mandatory always, and don't allow further nesting.

https://api.britishtriathlon.org/openactive/v1/events have an additional level of Event but have specified that via btf:componentEvent which is a different usecase, as it's not inheriting parent props.

[petewalker]

From a validator perspective, it would be cleaner if the subEvent had its own type if we're going down this route. We're adding extra complexity to the rules engine (and to developers' heads) if fields are only required depending on where an object type sits in the tree.

Also, semantically - what does subEvent then really mean in this context?

[lukehesluke]

@petewalker Agree that it sounds like they should be separate types to make their distinctions simpler to spec

[lukehesluke]

@nickevansuk @petewalker I'd like to push on this

We aggregate events which have multiple subEvents. Each of these subEvent items has its own start time

The event doesn't pass the validator (https://github.com/openactive/data-model-validator) because it itself doesn't have a startDate even though there is no meaningful single value that startDate could possible have as the event itself is a collection of startDates

I'm not au fait with the schema.org rules, but could this be something like converting the top-level Event into something like an "EventCollection" which MUST have a subEvent array and MUST NOT have a startDate/endDate?

[nickevansuk]

@lukehesluke this proposal contends to change this entirely: https://github.com/openactive/modelling-opportunity-data/issues/63

It's suggestion would mean that EventSeries -(subEvent)-> Session would become the new structure instead of Event -(subEvent)-> Event.

Are you able to make your comment in the context of that proposal?

[ldodds]

Just reviewing this, as Nick notes is superceded by #63.

But brief comments:

"Currently .startDate and .endDate are allowed in the root level of an Event as well as in a subEvent". That's not the case, the current spec doesn't restrict this type of usage.

A subEvent is a separate, sub-event that is part of a longer running item. Either as part of a series, or as a longer (e.g. multi-day) event, so its incorrect to always require a subEvent where there is just a single instance.

I think #63 covers the broader set of use cases that have been discussed so far here and in the beta namespace.