New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Change to OSM opening_hours format for times and dates #328
Conversation
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.
Updates files table noting deprecation of system_hours and system_calendar
Thanks! The spec looks neater having system_hours and system_calendar endpoints removed. Questions:
|
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:
I'm tagging those who have expressed interest in this or related issues. |
@mplsmitch This looks great to me! |
We'd support this change. Thanks @mplsmitch |
IBI Group is supportive of this change. |
Adds guidance on the use of opening_hours for systems and stations
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just some typos/formatting in the JSON examples.
Fix typos Co-authored-by: Daniel <36266644+nbdh@users.noreply.github.com>
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. |
Co-authored-by: Daniel <36266644+nbdh@users.noreply.github.com>
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. |
This pull requests mixes 'the proposal' and 'formatting fixes'. I would suggest not to do so. |
+1 from Transit |
gbfs.md
Outdated
* [OSM opening_hours validation tool](https://openingh.openstreetmap.de/evaluation_tool/) | ||
* [OSM opening_hours project and code libraries](https://github.com/opening-hours) | ||
|
||
Hours and dates of operation SHOULD be published even in cases where services are continuously available 24/7. During periods when a system or station is outside of opening hours, stations SHOULD be set to `is_renting = false`. During these periods, `station_status.json.num_bikes_available` and `station_status.json.num_docks_available` SHOULD reflect the number of vehicles and docks that would be available if the system or station were open. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There should be a separate PR to improve documentation / meaning of the is_disabled wrt opening hours.
+1 from Stae |
Entur supports this proposal |
+1 from nextbike |
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. |
+1 from Spin on this proposal. |
This vote has now closed, and it passes! Votes in favor: There were no votes against. We'll update the documentation as discussed, and then we will tag and merge this into v3.0-RC2 in the coming weeks. |
Updates is_disabled definition and adds information regarding setting or hours and dates of operation
## Problem The files system_hours.json and system_calendar.json were removed in #328. However, the spec says these files were “deprecated”, which usually means permitted, but discouraged. ## Solution Replace "deprecated” with "removed" for the files system_hours.json and system_calendar.json in the spec.
## Problem The files system_hours.json and system_calendar.json were removed in #328. However, the spec says these files were “deprecated”, which usually means permitted, but discouraged. ## Solution Replace "deprecated” with "removed" for the files system_hours.json and system_calendar.json in the spec.
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?
Which files are affected by this change?
gbfs.md: