Proposal: Add estimatedDuration Property for ScheduledSessions

peter-dolkens commented 5 years ago

Proposer

England Athletics (RunTogether) / LTA

Use Case

In Clubspark, we capture session durations as a range (0-30mins, 30-60mins, 60-90mins, 90+)

Why is this not covered by existing properties?

The spec states that we must return an ISO8601 format duration, however it's also validating that this duration is non-zero, so we're unable to just provide the minimum Duration

Please provide a link to example data

https://api.runtogether.co.uk/odi/public/courses

"subEvent": [
  {
    "type": "ScheduledSession",
    "url": "https://groups.runtogether.co.uk/RunningFree/Runs/Summary/ea313abf-4aad-4341-a827-da059c3ee00f",
    "startDate": "2018-10-01T17:00:00+01:00",
    "endDate": "2018-10-01T17:00:00+01:00",
    "duration": "PT0S",
    "eventStatus": "https://schema.org/EventScheduled",
    "name": "First steps"
    ...
  }
],

Proposal

We'd like to propose an estimatedDuration field of type QuantitativeValue and unitCode of MIN

This follows the pattern of other duration ranges in schema.org that use QuantitativeValue:

And follows the property naming pattern of estimatedX:

Validation rules should state that: if estimatedDuration is provided, then duration MUST not be provided. This ensures accurate and consistent data.

Beta property

(Class) Property	Expected Type	Description
(`schema:Event`) `beta:estimatedDuration`	`schema:QuantitativeValue`	A property that allows an Event duration to be represented as a range (e.g. 0-30mins, 30-60mins, 60-90mins, 90+).

Example

"subEvent": [
  {
    "type": "ScheduledSession",
    "url": "https://groups.runtogether.co.uk/RunningFree/Runs/Summary/ea313abf-4aad-4341-a827-da059c3ee00f",
    "startDate": "2018-10-01T17:00:00+01:00",
    "endDate": "2018-10-01",
    "beta:estimatedDuration": {
      "type": "QuantitativeValue",
      "minValue": 0,
      "maxValue": 30,
      "unitCode": "MIN"
    },
    "eventStatus": "https://schema.org/EventScheduled",
    "name": "First steps"
    ...
  }
],

peter-dolkens commented 5 years ago

@nickevansuk I didn't mention endDate in this proposal yet, as I thought it could still be useful as an indicator of when a session MUST be completed by (e.g. Your session starts at 2pm, and SHOULD take 20-40 minutes, and it MUST be completed by 3pm, because we start booking the next session from that time)

Mostly for those sessions where the start time may be a little more flexible too. (Turn up BY 2pm, but your class may not start until 2:15pm)

Wouldn't always be used, but may come in useful in some scenarios.

Let me know what you think.

nickevansuk commented 5 years ago

Looks great! Just updated your example from beta:exampleDuration to beta:estimatedDuration (assume that was a typo?).

endDate being included makes sense to me, though arguably if there was an endDate one could also calculate the duration as the "maximum duration", which undermines the proposed validation rules. Good discussion to have on this.

For now I'll go ahead and add this to the beta namespace as you've specified. I've amended your proposal to include this too.

peter-dolkens commented 5 years ago

endDate being included makes sense to me, though arguably if there was an endDate one could also calculate the duration as the "maximum duration", which undermines the proposed validation rules. Good discussion to have on this.

Yeah, I think it's important to decide how we want to define StartTime, EndTime, and estimatedDuration. If we wish to distinguish between

StartTime/EndTime: When a session MUST start after, and complete by
estimatedDuration: How long a session MAY be

There is a difference, based on those definitions, but those may not be the definitions we wish to use for this specification.

As a real life example, if I take driving lessons, I pay by the hour, so they are ALWAYS 2 hours long, but the start time often varies between 5pm and 6pm, depending on when my instructor becomes available. I do know that I'm going to be home by 7pm though.

I would imagine many sports coaching sessions behave in a similar fashion.

ldodds commented 5 years ago

Looks good to me, I'd suggest as part of beta testing we ask others if they would find this useful, I think that discussion will help flush out the intended requirements to inform validation rules.

nickevansuk commented 5 years ago

In Parkrun's case they've found that including an endTime is problematic and actually puts people off, so they just include startTime on their website.

Perhaps on this basis endTime, endDate and duration should actually be optional?

croesus commented 4 years ago

A potential difficulty with an optional endDate comes when searching for sessions that intersect a date and time. The logic for this is usually

startDate <= dateTimeOfInterest AND endDate >= dateTimeOfInterest

If endDate is unspecified and assumed to be "anytime after startDate", then this search would match any event that started before the dateTimeOfInterest, even if that was a long time before.

That said , it looks like endDate is optional so the search code above would already have to deal with using startDate + duration as endDate. This proposal would add to that:

endDate = max(endDate, startDate+duration, startDate+estimatedDuration.maxValue)

It might be simpler to require endDate as the maximum possible endpoint, but have duration or estimatedDuration take precedence when an event is displayed. Even Parkrun packs up eventually!

On a side note - @peter-dolkens example above has a date with no time as the endDate, which is midnight at the start of that day in ISO8601. This puts endDate before startDate and would be rejected as inconsistent data.

peter-dolkens commented 4 years ago

@croesus forgive my example - it appears we’ve used the naive mapping of .net DateTime to StartDate/EndDate in the sample feed.

The OA spec actually contains both Start/End Date and Start/End Time, so ideally we should be using those appropriately, with both EndDate and EndTime optional.

In reference to your search user case, ClubSpark usually works based on individual sessions when searching, and work our way up to the containing course, as a coach may have added a course that runs an entire year, but if they haven’t yet populated the upcoming sessions, then there is little point in returning them in results until that time.

nickevansuk commented 4 years ago

Relevant points from the summary of the W3C call on 12 Feb 2020:

Discussion of this became complex, because of the need to balance:
- the reluctance of some publishers to provide a duration or endDate at all on their Events, for fear of demotivating people.
- a desire for strong validation confirming that startDate, endDate, and duration are not self-contradictory
- the need to specify time ranges in order to give at least an indicative idea of the time commitment involved in participating in an activity
- supporting applications relying upon the presence of these values for scheduling, etc.
No satisfactory solution bridging all of these was arrived at on the call, and it was agreed to continue the discussion asynchronously on the GitHub thread.

thill-odi commented 3 years ago

Two possibilities:

Introduce indicativeDuration from the Routes spec, and make one of duration or indicativeDuration REQUIRED.
retain the spec as is but improve guidance for schedulingNote

thill-odi commented 3 years ago

Notes from call 7 Oct 2020: simple solution would be just to leave this as a beta property, particularly as data consumers don't appear ready to process this at the moment.

openactive / modelling-opportunity-data