search

openactive / modelling-opportunity-data

OpenActive Modelling Opportunity Data specification
https://www.openactive.io/modelling-opportunity-data/
Other
6 stars 6 forks source link

Proposal: Include defined profile of OpeningHoursSpecification #258

Open nickevansuk opened 3 years ago

nickevansuk commented 3 years ago

Proposer

imin, MCRactive

Use Case

Opening hours are frequently provided in a condensed format, such as the below:

Screenshot 2021-01-12 at 21 25 28 [1] [2] [3]

Screenshot 2021-01-12 at 22 05 00 [4]

Screenshot 2021-01-12 at 22 09 44 [5]

Screenshot 2021-01-12 at 21 53 51 [6]

Screenshot 2021-01-12 at 21 49 26 [7]

Why is this not covered by existing properties?

The current version of the specification does not specify a model profile for OpeningHoursSpecification, instead relying on the less restrictive schema.org model definition. OpenActive tooling had previously assumed that OpeningHoursSpecification within dayOfWeek was a single value.

Efforts to document the use of OpeningHoursSpecification have revealed that common use of this online is to provide dayOfWeek as an array.

Proposal

To create convergence in implementation, it is proposed that OpeningHoursSpecification be defined with the Modelling Opportunity Data specification as follows, in line with Google's own recommendations:

Required properties

Property Expected Type Description
@type Text Must always be present and set to "@type": "OpeningHoursSpecification"
dayOfWeek Array of DayOfWeek

Defines the days of the week upon which the opens and closes values are specified. Note this property is optional when used within specialOpeningHoursSpecification.


Example

"dayOfWeek": [
 "https://schema.org/Saturday",
  "https://schema.org/Sunday"
 ]
closes Time

The closing time. Set "00:00" for the value of opens and closes to indicated the Place is closed on the specified days. Note this property is required when used within specialOpeningHoursSpecification.


Example

"closes": "17:00"
opens Time

The opening time. Set "00:00" for the value of opens and closes to indicated the Place is closed on the specified days. Note this property is required when used within specialOpeningHoursSpecification.


Example

"opens": "09:00"

Note that dayOfWeek is defined above only as an array, following the OpenActive convention of having each property defined as either a single value or an array, to increase usability of the data and specifications.

Optional properties

Property Expected Type Description
validFrom Date

The date when the item becomes valid. The item will be valid at the beginning of the specified day.


Example

"validFrom": "2018-01-22"
validThrough Date

The date after which the item is no longer valid. The item will cease to be valid at the end of the specified day.


Example

"validThrough": "2018-01-27"

specialOpeningHoursSpecification

It is also proposed that use of schema.org's existing specialOpeningHoursSpecification property be defined within the specification, as follows:

The specialOpeningHoursSpecification property of the Place is used to explicitly override standard opening hours brought in scope by openingHoursSpecification, using the validFrom and validThrough properties to define the applicability of such overrides.

Usage and processing

It is proposed that the specification should also include processing and usage specification for the following, in line with Google's own recommendations:

1) Definition of "Open all day" as "opens": "00:00", "closes": "23:59" 2) Definition of "Closed all day" as "opens": "00:00", "closes": "00:00" 3) Usage example of "late opening hours" as "opens": "18:00", "closes": "03:00" 4) Use and definition of "dayOfWeek": [ "https://schema.org/PublicHolidays" ] as "a placeholder for all official public holidays in the location in which the Place is located. It can be used to indicate opening hours on public holidays, overriding general opening hours for the day of the week on which a public holiday occurs". 5) Use of validFrom and validThrough to specify seasonal opening hours within openingHoursSpecification (optional), and override applicability within specialOpeningHoursSpecification (required). 6) Use and definition an OpeningHoursSpecification within specialOpeningHoursSpecification with an undefined dayOfWeek as representing "every day".

Example

This allows the following example, assuming it is also closed during January due to COVID-19, to be easily and concisely specified in JSON:

Screenshot 2021-01-12 at 21 49 26 [7]

"openingHoursSpecification": [
  {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": [
      "https://schema.org/Monday",
      "https://schema.org/Tuesday",
      "https://schema.org/Wednesday",
      "https://schema.org/Thursday"
    ],
    "opens": "06:00",
    "closes": "13:00"
  },
  {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": [
      "https://schema.org/Monday",
      "https://schema.org/Tuesday",
      "https://schema.org/Wednesday",
      "https://schema.org/Thursday"
    ],
    "opens": "16:00",
    "closes": "20:00"
  },
  {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": [
      "https://schema.org/Friday"
    ],
    "opens": "06:00",
    "closes": "12:00"
  },
  {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": [
      "https://schema.org/Saturday",
      "https://schema.org/Sunday",
      "https://schema.org/PublicHolidays"
    ],
    "opens": "08:00",
    "closes": "12:00"
  }
],
"specialOpeningHoursSpecification": [
  {
    "@type": "OpeningHoursSpecification",
    "opens": "00:00",
    "closes": "00:00",
    "validFrom": "2021-01-01",
    "validThrough": "2021-01-31"
  }
]
nickevansuk commented 3 years ago

Given all current implementers of OpeningHoursSpecification are engaged in OpenActive Open Booking API implementation, the tooling has been updated to reflect dayOfWeek as an array based on the above, to allow implementers to make a quick change that will ensure implementation consistency going forward across the OpenActive ecosystem. This is a breaking change within the validator, however it is not a breaking change within the modelling specification as this property and the OpeningHoursSpecification type were previously underspecified.

Please comment if this creates issues, as dayOfWeek can be made available as both a single value and an array within the tooling, though this would be at the expense of adding complexity to the next version of the specification for the sake of backwards compatibility with the previous de facto standard.

nickevansuk commented 3 years ago

Following discussion in the W3C Community Group call on 13 January 2021 this has been moved into "Agreed in scope for next revision" for 2.1