Change to OSM opening_hours format for times and dates

[mplsmitch]

Adds fields to system_information and station_information to describe times and dates of operation using OSM opening_hours format. Deprecates system_hours and system_calendar endpoints.

What problem does your proposal solve? Please begin with the relevant issue number. If there is no existing issue, please also describe alternative solutions you have considered.

Currently GBFS sues a proprietary format to describe hours and dates of service. This format lacks flexibility to address new use cases such as setting hours for individual stations.

What is the proposal?

This proposal changes the format used to describe hours and dates of operation from the current GBFS proprietary formats to Open Street Map’s opening_hours format. Changing to this format adds additional functionality and is supported by existing code libraries and tools. This change will allow support for calendar exceptions such as holidays and allows operators to set different operating hours per station.

This change was initially discussed in #6 . A detailed writeup of this proposal is contained in this document. The need for different hours per station was covered in #98 . This change may also facilitate a future proposal to set valid times and dates for pricing plans as discussed in #298 .

Is this a breaking change?

• Yes
• No
• Unsure

Which files are affected by this change?

gbfs.md:

• system_information.json
• station_information.json

[kanagy]

Thanks! The spec looks neater having system_hours and system_calendar endpoints removed. Questions:

• Is the OSM format possibly protected by a license that could limit it's use?
• Would it be useful to provide some guidance in this PR for what real-time systems should set in GBFS data when they are outside of opening hours? E.g. we've seen different systems use different mechanisms: setting is_disabled, is_renting, is_returning, setting the number of bikes/docks to 0 or just straight up shutting down the feed for winter.

[mplsmitch]

We're planning to call a vote on this proposal soon and we would like to understand the level of support for this change. There are other proposals coming up that depend on the passing of this PR. This is a breaking change that would become part of v3.0.

Please let us know the following:

• Are you willing to vote in support of this proposal as it's currently written?
• If not, are there any changes that you would require in order to support the proposal?

I'm tagging those who have expressed interest in this or related issues.
CC: @contra @brookemckim @evansiroky @skinkie @sven4all @cizmarf @cmonagle

[yocontra]

@mplsmitch This looks great to me!

[cmonagle]

We'd support this change. Thanks @mplsmitch

[evansiroky]

IBI Group is supportive of this change.

[nbdh]

Just some typos/formatting in the JSON examples.

[nbdh]

Following up on @josee-sabourin mail here.

Though we are publishing the existing feeds for all our systems, we only have two with limited opening hours, so practical usage is rather low.

About a year ago I spent a quite some time to implement some kind of conversion from OSM opening hours format to GBFS format, as we started to use (a subset of the) OSM format internally for defining the opening hours. (As a producer) we'll happily throw that away again and just go with publishing what we have anyways - so I guess we support the proposal in general.

I can't evaluate how this consumers will like this change. The OSM format allows some pretty tricky stuff (well, reality is complex). On the other hand, there are some libraries available e.g. to clarify "is it open right now?", but the current format definitely answers this question more easily without using 3rd party library. Answering this question for the OSM format eventually requires (depending on the used features) additional context, e.g. coordinates, country and state, for example to evaluate whether or not today is a public holiday or when sunrise/sunset is.

This change also means that validating a GBFS feed in theory also means to validate the opening hours.

[mplsmitch]

I hereby call a vote on this proposal.

Voting will be open for 10 full calendar days until 11:59PM UTC on December 9, 2021.

Please vote for or against the proposal, and include the organization for which you are voting in your comment.

Please note if you can commit to implementing the proposal.

[skinkie]

This pull requests mixes 'the proposal' and 'formatting fixes'. I would suggest not to do so.

[cmonagle]

+1 from Transit

[kanagy]

Hi, could this clarify how free_bike_status.json should behave wrt. opening hours since that feed doesn't have is_renting field? I.e. if a system is outside of opening hours, would there be no free bikes? Also, in this paragraph stations SHOULD be set to is_returning=false too outside of opening hours.

We're trying to figure out whether we MUST check system_information.opening_hours when ingesting real-time feeds before surfacing bikes (i.e. this is a breaking proposal) or we can continue gating by is_renting=false, is_returning=false and no bikes in free_bike_status.

[mplsmitch]

if a system is outside of opening hours, there would not be any vehicles available for rent, including free floating bikes. This can be added to the system_information.opening_hours definition.

Also, in this paragraph stations SHOULD be set to is_returning=false too outside of opening hours.

Actually this is not the case - systems typically allow you to end a rental and/or return vehicles outside of opening hours.

We're trying to figure out whether we MUST check system_information.opening_hours when ingesting real-time feeds before surfacing bikes (i.e. this is a breaking proposal) or we can continue gating by is_renting=false, is_returning=false and no bikes in free_bike_status.

This one is harder to answer - It seems like for now, you would have to check system_information.opening_hours in the case of free bikes. In station_status , the num_bikes_available and num_docks_available fields give the numbers that would be available if the station were set to allow rentals. There's a long thread on how this came to be in #94 . The reason was so that you could plan a trip or reserve a vehicle at 5:45 when the system opened at 6:00. There's no equivalent to num_bikes_available in free_bike_status but there's also no where that it says there should be no bikes in free_bike_status when rentals aren't allowed, only when there are no bikes on the street. If there are bikes on the street, they could still appear in free_bike_status when opening_hours evaluates to closed, that's no different from the current spec, it's just that the format and location of the hours of operation are different.

[kanagy]

I see. There's also is_disabled field in free_bike_status which says "This field is used to indicate vehicles that are in the field but not available for rental." It sounds like this field should then be set to false outside of opening hours?

[mplsmitch]

I don't know if I agree with that. With station based ( docked) vehicles that's not really how it works and I think it should be the same for free floating. The numbers represented by ststion_status.num_bikes_available and num_docks_available are the number of functional bikes/docks that would be available if is_renting = true. Suppose there's a free floating vehicle with a dead battery and you set 'is_disabled= true' when the system is closed. In the above scenario where you're planning a trip at 5:45 for the system that opens at 6:00, it would appear that this vehicle will be available for rent at 6 but it won't be.

[kanagy]

There should be a separate PR to improve documentation / meaning of the is_disabled wrt opening hours.

[yocontra]

+1 from Stae

[testower]

Entur supports this proposal

[nbdh]

+1 from nextbike

[heidiguenin]

Voting on this PR closes in 2 calendar days. Please vote for or against the proposal, and include the organization for which you are voting in your comment. Please note if you can commit to implementing the proposal.

[ncancelliere]

+1 from Spin on this proposal.

[heidiguenin]

This vote has now closed, and it passes!

Votes in favor:
Transit (consumer)
Stae (consumer)
Entur (consumer)
nextbike (producer)
Spin (producer)

There were no votes against.
Thank you to everyone who took the time to review and to vote on this!

We'll update the documentation as discussed, and then we will tag and merge this into v3.0-RC2 in the coming weeks.