Describing free events, advanced booking requirements, etc

[nickevansuk]

Proposer

ODI

Use Case

When the event is free there needs to be a consistent way to describe how to access such an event.

Why is this not covered by existing properties?

Ways to describe free events with type Offer are currently ambiguous.

Proposal

Bookable free Offers

To allow free opportunities to be booked through the same mechanism as paid opportunities, the following format must be used for a free bookable Offer. Note the “price” is set to the string “0”.

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "offers": [
    {
      "type": "Offer",
      "url": "https://www.letsride.co.uk/rides/mayor-of-londons-sky-ride/book",
      "price": "0"
    }
  ]
}

Free Events

For universally free events (distinct from those that have one or more free Offers as well as paid Offers) that require booking in advance, but are accessible for free to anyone, the following property must also be set:

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "isAccessibleForFree": true
}

Events that do not require booking in advance / Just turn up and pay

For events that may or may not be bookable, but are accessible without necessarily requiring booking in advance (i.e. “just turn up and pay”), the following property should also be set.

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "publicAccess": true
}

Just turn up for free

For events where no booking is required (though it may be available via an Offer) and the participant can “just turn up for free”, the above two properties can be used in combination:

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "isAccessibleForFree": true,
  "publicAccess": true
}

Beta use

These properties are all present in schema.org, and can be used freely during beta.

[ldodds]

For the "Events that do not require booking in advance / Just turn up and pay" and "Just turn up for free" use cases, I'm going to suggest we use different property.

publicAccess is a for Place not an Event.

I think the key requirement is to indicate whether an Event is bookable in advance or whether you have to turn up and pay on the day.

Events that are bookable in advance will have one or Offers that have url properties that allow a user to book and/or an id linking to a booking API. Those that aren't won't have this information. So this is already covered by the model.

However to make this clearer, and to be consistent with what we're doing with free events, I'm suggesting that we add a new property: isBookableInAdvance with a true/false value. False indicates you must turn up an pay.

We can specify a conformance rule to generate an error if is not bookable in advance, but there's an Offer with a URL.

And perhaps generate a suggestion if there is an Offer with no url, to indicate that the isBookableInAdvance property can be used to clarify whether you have to book on the day.

[nickevansuk]

I'd actually suggest the requirement is isAccessibleWithoutBooking or similar - as the main thing the user needs to understand is whether the Offers provided are mandatory or whether they can expect to just turn up.

isBookableInAdvance: false /=> isAccessibleWithoutBooking: true, as isBookableInAdvance might be related to whether you can book in advance via the API, whereas isAccessibleWithoutBooking is a statement about the event itself (similar to isAccessibleForFree). If booking is required it might be via phone, e-mail, fax, or smoke signal...

Conformance rule and suggestion sound great!

[ldodds]

OK, so:

isAccessibleWithoutBooking: true

A user can turn up to an Event and pay on the day. Or its free. User can book in advance or turn up.

isAccessibleWithoutBooking: false

A user must book in advance to attend the Event.

There MUST be at least one Offer with either a url or an id.

[nickevansuk]

Additional Analysis of isAccessibleWithoutBooking and Prepayment

Noting an overlap with the Google Reserve concept of PrepaymentType, which represents whether or not online payment is possible (as the offers might be accurate in price, but can be paid on the door). Google Reserve has three options:

• Required: The user has to pay this service at the booking time.
• Optional: The user can choose to pre-pay this service at the booking time or later, but it is not required in order to book.
• Not supported The prepayment is not supported for this service.

It should be noted that where Google Reserve is capturing what is possible within the Reserve system, the semantics of Event are more concerned with describing the properties of the event itself: hence if online booking is "not supported" by Reserve, that does not necessarily mean that it is "not possible" to book by a different means.

Considering the possible states with respect to advanced booking rather than prepayment, along with the two properties proposed so far, neither are able to represent the options here:

	isAccessibleWithoutBooking: true	isBookableInAdvance: true
Advanced Booking Required	false	?
Advanced Booking Optional	true	true
Advanced Booking Not Possible	true	false

New Proposal

Hence instead of isAccessibleWithoutBooking or isBookableInAdvance, we can provide total clarity with two new properties on both Event and FacilityUse:

• advancedBooking - requirement for Event/FacilityUse to be booked in advance
• prepayment - requirement for Event/FacilityUse to be paid for in advance

Each of which have potential values of:

• https://openactive.io/Required
• https://openactive.io/Optional
• https://openactive.io/None

With an additional two conformance rules:

• A value for prepayment MUST NOT be supplied if advancedBooking == https://openactive.io/None
• If advancedBooking != https://openactive.io/None, there MUST be at least one Offer with either a url or an id.

Additionally in terms of booking functionality:

• If prepayment != https://openactive.io/Required, the booking process must allow for completion of the booking without taking payment (although noting that in future deposit/no-show fees/forced capture may require payment details to be taken even if prepayment is not required).

Advanced Booking / Prepayment State Matrix

	Prepayment Required	Prepayment Optional	Prepayment Not Possible
Advanced Booking Required	advancedBooking: Required, prepayment: Required	advancedBooking: Required, prepayment: Optional	advancedBooking: Required, prepayment: None
Advanced Booking Optional	advancedBooking: Optional, prepayment: Required	advancedBooking: Optional, prepayment: Optional	advancedBooking: Optional, prepayment: None
Advanced Booking Not Possible	N/A	N/A	advancedBooking: None

[ldodds]

I've updated this issue title to reflect the evolving discussion. Tagging in @drchristhorpe for overlap with booking specification.

@nickevansuk suggest we discuss on community group call this afternoon.

I've restated the key requirements below:

1. Some events (or uses of a facility) are free. A participant does not have to pay
2. Some events (or uses of a facility) must be booked in advance. For example a user may not be able to attend an Event if they have not pre-booked. In other cases they may be able to "pay on the door". A free event might still need to be booked.
3. Some events (or uses of a facility) must be paid for in advance (as part of booking). In others a user may be able to book, but then pay on the door

Neither of the second two requirements are currently covered in the modelling or booking specifications.
The third requirement has not come up as part of looking at alignment with Google Reserve. It's not been raised otherwise.

I think the proposal makes sense, but I think the properties you're describing should be properties of an Offer and not an Event or FacilityUse.

For two reasons:

• keeps the interpretation of payment/booking/pricing in the Offer, rather than scattered across Offer and other parts of the model (Event, FacilityUse, perhaps Route, etc in future)
• communicates meaning better, as we're really describing the rules by which someone accepts an offer, e.g. do they need to do it in advance, do they need to pay in advance, etc.
• consistent with isCancellable and cancellationValidUntil properties added in booking spec
• gives more flexibility and extensibility, e.g. where pre-payment is not required for members, but non-members may need to pay in advance, or where their may be a time-limited offer at a cheaper price but payment is required in advance, or where we need to capture payment methods differently for advance bookings, etc

The following would be an Offer that allows someone to book in advance. If they do they'll need to pay 5 quid. Otherwise they can choose to pay a fiver on the day.

{
  "type": "Offer",
  "id": "...",
  "url": "...",
  "price": 5.0,
  "priceCurrency": "GBP",
  "advanceBooking": "https://openactive.io/Optional",
  "prepayment": "https://openactive.io/Required"
}

Regardless of where the properties are added, there's some implications for the booking API. At a minimum this would need to be revised to:

• explain how these properties are to be interpreted, in terms of choices offered to users
• explain that if pre-payment is not required, then booking can still proceed if advance booking is supported
• ensure that pre-payment is considered in the context of cancellations, e.g. not refunding where there is no need to do so

There is an issue for this noted here

Support for partial payments, e.g. booking now and paying later (but before the event) is currently out of scope for v1.0 of the booking spec.

But there are also implications for API calls. E.g. if an Event must be booked in advance and there is no need to take payment (because its free, or because the user can choose not to pay until later), then could the apply calls be simplified? There is an issue for this here. This could be done as a single call. There are various options for doing that.

[nickevansuk]

I agree with all the rationale of putting this in Offer, in terms of flexibility and extensibility, interpretation of payment/booking/pricing, communicates meaning better etc.

Only thing that I'm wondering is whether this makes it more difficult to display a notice like "Advanced Booking Required" in the UI at the event level, however this could be inferred from the Offers in aggregate in the same way as the primary price being displayed.

In the future we will likely want to signify that an offer is a "headline price" (see #116), this same logic could be applied to aggregate advanceBooking and prepayment in a meaningful way for the UI requirement above. In the "headline price" proposal, the AggregateOffer subclasses Offer, so Offer still makes sense for this.

So noting these considerations, agree with your revision @ldodds 👍