Add virtualLocation property to Event

thill-odi commented 4 years ago

Proposer

@nickevansuk (ODI/imin), with contributions from @thill-odi (ODI) and @lukehesluke (imin).

Use Case

An Opportunity provider is providing new means of accessing led classes online, as well as or instead of at a physical location.

This proposal obviously has increased salience in light of COVID-19 isolation measures.

Why is this not covered by existing properties?

The existing data model deals only with physical locations, not those available via online technologies.

Please provide a link to example data

See e.g. https://www.cococollective.co.uk/booking/ for a yoga studio that has recently moved to online events to replace physical ones.

Proposal

The proposal would be to make a virtualLocation property available to all Opportunity types except Slot, FacilityUse, and IndividualFacilityUse. The value of this property would be a schema.org VirtualLocation, characterised in particular by a name and url, both of which are REQUIRED.

Inheritance

It is assumed that virtualLocation is fully heritable, so that values defined on parent objects (e.g. EventSeries, SessionSeries) are applicable to child objects (e.g. Event, ScheduledSession). Where this value is defined on a child object, however, the value defined at this lower level takes precedence over any defined higher up the chain.

Example

"location": {
    "@type": "Place",
    "name": "Middlesbrough Sports Village",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "geo": {
      "type": "GeoCoordinates",
      "latitude": 54.543964,
      "longitude": -1.20978500000001
    }
},
"virtualLocation": {
    "@type": "VirtualLocation",
    "name": "Zoom Video Chat",
    "url": "https://zoom.us/j/1234567890/signup"
}

thill-odi commented 4 years ago

See also #225, #226, #227.

nickevansuk commented 4 years ago

Should we make the name of the VirtualLocation optional or recommended, as it's not essential to the customer experience?

nickevansuk commented 4 years ago

Also should we include description of the VirtualLocation?

As Bookwhen have mentioned, access to the URL of the service in many cases will be behind a paywall - though it might also be a "signup" URL. Hence the url is potentially more a consideration for the Open Booking API than for this Modelling Specification. This means the description of means of access is actually more important.

For example, the following screenshot from ClassPass illustrates the types of data that could be in the description:

WhatsApp Image 2020-03-20 at 13 41 23

There's also this additional data, which could be included somewhere too? I guess attendeeInstructions already covers this: WhatsApp Image 2020-03-20 at 13 41 40

nickevansuk commented 4 years ago

Also noting that virtualLocation is likely to exist at SessionSeries OR at ScheduledSession level - as some URLs are generated per-event, and some use the same one each week

nickevansuk commented 4 years ago

From discussions with @jopotts cases where the virtual location is private (e.g. behind a paywall), we suggest that virtualLocation should not be included.

This allows the virtualLocation to reliably represent direct access to the session with a "View Livestream" button - for a UI that might show "sessions happening right now", for example.

Consistent with physical sessions: the Offer url can then be used for the link to purchase access or sign-up, and the Event url can signpost to a general page about the session.

nickevansuk commented 4 years ago

Relevant points from the summary of the W3C call:

After discussion about the merits of supporting multiple broadcast platforms, the consensus was to keep beta:virtualLocation as a singular not array, as multiple broadcast platforms are likely an edgecase in this sector. We agreed to re-evaluate this before moving the property out of beta.

nickevansuk commented 4 years ago

Updated Proposal

The proposal would be to make a virtualLocation property available to all Opportunity types except Slot, FacilityUse, and IndividualFacilityUse. The value of this property would be a schema.org VirtualLocation, characterised in particular by a url, name and description, at least one of which is REQUIRED.

Note where the virtual location is private (e.g. behind a paywall), the VirtualLocation url should not be included.

This allows the VirtualLocation url to reliably represent direct access to the session with a "View Livestream" button - for a UI that might show "sessions happening right now", for example.

Consistent with physical sessions: the Offer url can then be used for the link to purchase access or sign-up, and the Event url can signpost to a general page about the session.

Inheritance

It is assumed that virtualLocation is fully heritable, so that values defined on parent objects (e.g. EventSeries, SessionSeries) are applicable to child objects (e.g. Event, ScheduledSession). Where this value is defined on a child object, however, the value defined at this lower level takes precedence over any defined higher up the chain.

Example

"beta:virtualLocation": {
    "type": "VirtualLocation",
    "name": "Zoom Video Chat",
    "url": "https://zoom.us/j/1234567890/signup",
    "description": "Please log into Zoom a few minutes before the event, and mute your mic while you wait for the session to start"
}

openactive-bot commented 4 years ago

This proposal has been added to the Beta namespace as follows:

(Class) Property	Expected Type	Description
(`schema:Event`) `beta:virtualLocation`	`pending:VirtualLocation`	Describes a means of electronic access to a shared virtual space.

nickevansuk commented 3 years ago

To support private events behind a paywall (as per https://github.com/openactive/modelling-opportunity-data/issues/224#issuecomment-603302198), and public events that are protected from e.g. "Zoombombing", an accessId and accessCode must also be supplied for the VirtualLocation:

accessId: The identifier required to access the VirtualLocation from any device, without requiring the URL, e.g. the meeting ID.
accessCode: The password or pin required to access the VirtualLocation from any device, without requiring the URL, e.g. the meeting password.

New full example

"beta:virtualLocation": {
  "@type": "VirtualLocation",
  "name": "Zoom Video Chat",
  "url": "https://zoom.us/j/1234567890/signup",
  "accessId" : "1234567890",
  "accessCode" : "211277",
  "description": "Please log into Zoom a few minutes before the event"
},

openactive / modelling-opportunity-data