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 👍

[nickevansuk]

Also suggest default values of (if no properties provided)

  "advanceBooking": "https://openactive.io/Optional",
  "prepayment": "https://openactive.io/Required"

[nickevansuk]

@dolkensp @Jadecation @jopotts / @gregjoy1 @nickbaileyuk any thoughts on advanceBooking and prepayment in ClubSpark, Classfinder, Bookwhen, and Makesweat?

What do you think of the above? Specifically should this be set at the Offer or Event level?

@jopotts / @gregjoy1 - I know that you have a "Pay later"/"Offline payments" option in Bookwhen?
@Jadecation - you have a prepayment options?
@dolkensp & @nickbaileyuk - is this something you support?

[Jadecation]

Hi all, i have had a look at the matrix and believe that this covers all possible bases and seems to make sense. In my opinion the matrix needs to be at Offer level rather than Event level. In some cases organisers will have special offers i.e. buy 10 where you have to buy them all in advance but if you only buy one you can buy it on the day.

In reference to the pre-payment options the reality is that in some cases people will be able to (pre) pay online but other cases there will not be an online payment function so they will have to call and pay over the phone. This is a helpful piece of information for people to know how to progress with the booking so would be beneficial to include.

[peter-dolkens]

I think it definitely needs to be available on Offer, as I believe that gives us the flexibility to indicate that members might have different requirements to non-members, for example.

I understand the desire to put something up higher for ease of use, but I think #116 will cover that off nicely.

Specifically for Clubspark, we currently support multiple payment methods, including Stripe, Gocardless, Cheque, Cash, and in some cases, Third-Party wallets/accounts.

It may be worth considering a more fully featured definition of payment methods/requirements where we can actually indicate which methods are available, and if they are pre/post/recurring payment. I can see a scenario, for example, where a provider may only want to display offers where payment can be taken via Paypal.

[nickevansuk]

Great insights @Jadecation @dolkensp - following your observations, can I propose two further properties:

availableChannel

The following property defined on Offer:

  "availableChannel": [
    "https://openactive.io/TelephoneAdvanceBooking",
    "https://openactive.io/TelephonePrepayment",
    "https://openactive.io/OnlinePrepayment",
    "https://openactive.io/OpenBookingPrepayment"
  ]

The OpenBooking* relates to the availability of the OpenActive Open Booking API for this payment.

This fits with the language of the existing schema.org properties acceptedPaymentMethod and availableDeliveryMethod.

The idea is that TelephonePrepayment allows for "Booking AND Payment" over the phone, where as TelephoneAdvanceBooking only allows "Booking" but not payment (so this would not be valid if "prepayment": "https://openactive.io/Required" was set).

Note we might also want to add https://openactive.io/MobileAppPrepayment to the list later (#151).

Values for "OnlinePrepayment" and "OpenBookingPrepayment" in availablePrepaymentChannel are important as they can't be inferred by the presence of "id" or "url" on the Offer. The "id" and "url" (and "potentialAction" in #151) specify that booking is available via website, app, Open Booking API, but do not include anything about whether payment is available. OnlineAdvanceBooking (the existence of a "url" on Offer) and OpenBookingAdvanceBooking (the existence of an "id" on Offer) are arguably redundant as they can be inferred, however we could include these for completeness?

If specified at the Offer level this also allows for Online-only Offers, or a specific Offer for OpenBookingPrepayment.

Suggested conformance rules:

• "https://openactive.io/TelephoneAdvanceBooking" MUST NOT be used if "prepayment": "https://openactive.io/Required" or "advanceBooking": "https://openactive.io/None"
• "https://openactive.io/TelephonePrepayment", "https://openactive.io/OnlinePrepayment", "https://openactive.io/OpenBookingPrepayment" MUST NOT be used if "prepayment": "https://openactive.io/None"
• Only one of "https://openactive.io/TelephoneAdvanceBooking" or "https://openactive.io/TelephonePrepayment" MUST be used
• If "https://openactive.io/OnlinePrepayment" is set, a "url" MUST be present in the Offer
• If "https://openactive.io/OpenBookingPrepayment" is set, an "id" MUST be present in the Offer
• If "https://openactive.io/TelephoneAdvanceBooking" or "https://openactive.io/TelephonePrepayment" is used, a "telephone" property MUST be included in the Event "organizer".

acceptedPaymentMethod

Suggest we add https://schema.org/acceptedPaymentMethod to the OpenActive profile, with the following specifically recognised values, but with the option to use others from http://purl.org/goodrelations/v1 (including CheckInAdvance - American spelling of Cheque).

• http://purl.org/goodrelations/v1#Cash
• http://purl.org/goodrelations/v1#PaymentMethodCreditCard

We should specify that in the OpenActive context acceptedPaymentMethod specifically relates to payment available at the Event (e.g. "cash on the door") rather than prepayment.

Note that the above use of acceptedPaymentMethod is already implemented in Open Sessions and EMD in this way.

Suggested conformance rules:

• acceptedPaymentMethod MUST NOT be set if "prepayment": "https://openactive.io/Required"
• acceptedPaymentMethod MUST be set if "prepayment": "https://openactive.io/None"

Suggestion to split out: acceptedPaymentMethod per channel into a separate issue

It's unlikely that we'd want to specify the types of acceptedPaymentMethods available on OnlinePrepayment, OpenBookingPrepayment and TelephonePrepayment on a per-Offer or per-Event basis (much more likely these are a function of the booking system #147 or organizer),

Hence I wonder whether per-channel acceptedPaymentMethod at the Organization or BookingService level should be factored into #147 and split out into a separate issue, as on balance it seems orthogonal to the other two properties here? I've created a starter-for-10: #160

Thoughts?

[ldodds]

@nickevansuk can you split out any new suggestions into separate proposals?

[nickevansuk]

@ldodds ^ have created #121 (comment) and #161

[peter-dolkens]

Replying from mobile, so forgive formatting, I'll try and clean it up when I'm back at a PC. Regarding:

It's unlikely that we'd want to specify the types of acceptedPaymentMethods available on OnlinePrepayment, OpenBookingPrepayment and TelephonePrepayment on a per-Offer or per-Event basis

ClubSpark actually allows organizers to do exactly this. I'm not familiar with the history of the capability, but I could imagine it might be used when organizing fundraising events (cash only potentially) or when you know certain sessions are going to be staffed by different organizers (who might not have the same payment facilities or training as a regular organizer) I don't think it's critical, but something we do support. Peter Dolkens

…

On 13 Sep 2018, at 16:08, Nick Evans ***@***.***> wrote: @ldodds ^ have done — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[nickevansuk]

Interesting @dolkensp - do you have any data on how many organizers actually use the feature to create separate configurations per-Offer or per-Event?

[ldodds]

The advanceBooking and prepayment properties will be in the new 2.0 draft.

The additional proposals will be part of a later revision.

[peter-dolkens]

@nickevansuk sorry, haven't had a chance to look this up yet - pretty busy few weeks here.

I'll try get to it next week if that's not too late.