-
Notifications
You must be signed in to change notification settings - Fork 290
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
GBFS documentation versioning and and feed conformance #188
Changes from all commits
29db809
ea50d81
8cf699e
d746a64
1397ac4
fc77ed2
c2dc3d6
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -34,12 +34,25 @@ This specification has been designed with the following concepts in mind: | |
|
||
Historical data, including station details and ride data is to be provided by a more compact specification designed specifically for such archival purposes. The data in the specification contained in this document is intended for consumption by clients intending to provide real-time (or semi-real-time) transit advice and is designed as such. | ||
|
||
## Versioning | ||
The version of the GBFS specification to which a feed conforms is declared in the `version` field in all files. See [Output Format](#output-format). | ||
|
||
GBFS Best Practice defines that: | ||
|
||
_GBFS producers_ should provide endpoints that conform to both the current specification long term support (LTS) branch as well as the latest release branch within at least 3 months of a new spec `MAJOR` or `MINOR` version release. It is not necessary to support more than one `MINOR` release of the same `MAJOR` release group because `MINOR` releases are backwards-compatible. See [specification versioning](README.md#specification-versioning) | ||
|
||
_GBFS consumers_ should, at a minumum, support the current LTS branch. It highly recommended that GBFS consumers support later releases. | ||
|
||
Default GBFS feed URLs, e.g. `https://www.example.com/data/gbfs.json` or `https://www.example.com/data/fr/system_information.json` must direct consumers to the feed that conforms to the current LTS documentation branch. | ||
|
||
|
||
## Files | ||
This specification defines the following files along with their associated content: | ||
|
||
File Name | Required | Defines | ||
--------------------------- | ----------------------- | ---------- | ||
gbfs.json | Optional | Auto-discovery file that links to all of the other files published by the system. This file is optional, but highly recommended. | ||
gbfs_versions.json | Optional | Lists all feed endpoints published according to versions of the GBFS documentation. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm a little confused about where this sits. Does this file get published for every version? i.e. does this file appear in 1.0, 1.1 and 1.2 locations? Regardless, I propose we make it required in order to be able to find all of the relevant feeds. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This file would sit in all the versions. Proposal: Let's keep this optional for its incorporation into a "1.0" version. Technically, the change is backwards-compatible if we make the file optional. We could make this required in a future backwards compatibility breaking MAJOR change. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Let's update this field to indicate that it will probably become required in a future version so producers are encouraged to start publishing now. |
||
system_information.json | Yes | Describes the system including System operator, System location, year implemented, URLs, contact info, time zone | ||
station_information.json | Conditionally required | Mostly static list of all stations, their capacities and locations. Required of systems utilizing docks. | ||
station_status.json | Conditionally required | Number of available bikes and docks at each station and station availability. Required of systems utilizing docks. | ||
|
@@ -96,13 +109,16 @@ Field Name | Required | Defines | |
--------------------| ----------| ---------- | ||
last_updated | Yes | Integer POSIX timestamp indicating the last time the data in this feed was updated | ||
ttl | Yes | Integer representing the number of seconds before the data in this feed will be updated again (0 if the data should always be refreshed) | ||
version | Yes | String - GBFS version number to which the feed confirms, according to the versioning framework. | ||
data | Yes | JSON hash containing the data fields for this response | ||
|
||
|
||
Example: | ||
```json | ||
{ | ||
"last_updated": 1434054678, | ||
"ttl": 3600, | ||
"version": "1.0", | ||
"data": { | ||
"name": "Citi Bike", | ||
"system_id": "citibike_com" | ||
|
@@ -120,41 +136,75 @@ _language_ | Yes | The language that all of the contained f | |
\- name | Yes | Key identifying the type of feed this is (e.g. "system_information", "station_information") | ||
\- url | Yes | Full URL for the feed | ||
|
||
|
||
Example: | ||
|
||
```json | ||
{ | ||
"last_updated": 1434054678, | ||
"ttl": 0, | ||
"version": "1.0", | ||
"data": { | ||
"en": { | ||
"feeds": [ | ||
{ | ||
"name": "system_information", | ||
"url": "https://www.example.com/gbfs/en/system_information" | ||
"url": "https://www.example.com/gbfs/1/en/system_information" | ||
}, | ||
{ | ||
"name": "station_information", | ||
"url": "https://www.example.com/gbfs/en/station_information" | ||
"url": "https://www.example.com/gbfs/1/en/station_information" | ||
} | ||
] | ||
}, | ||
"fr" : { | ||
"feeds": [ | ||
{ | ||
"name": "system_information", | ||
"url": "https://www.example.com/gbfs/fr/system_information" | ||
"url": "https://www.example.com/gbfs/1/fr/system_information" | ||
}, | ||
{ | ||
"name": "station_information", | ||
"url": "https://www.example.com/gbfs/fr/station_information" | ||
"url": "https://www.example.com/gbfs/1/fr/station_information" | ||
} | ||
] | ||
} | ||
} | ||
} | ||
``` | ||
|
||
### gbfs_versions.json | ||
Each expression of a GBFS feed describes all of the versions that are available. | ||
|
||
The following fields are all attributes within the main "data" object for this feed. | ||
|
||
Field Name | Required | Defines | ||
------------------------| ------------| ---------- | ||
_versions_ | Yes | Array that contains one object, as defined below, for each of the available versions of a feed. The array must be sorted by increasing MAJOR and MINOR version number. | ||
\- version | Yes | String identifying the semantic version of the feed in the form X.Y. | ||
\- url | Yes | URL of the corresponding gbfs.json endpoint. | ||
|
||
```json | ||
{ | ||
"last_updated": 1434054678, | ||
"ttl": 0, | ||
"version": "1.0", | ||
"data": { | ||
"versions": | ||
[ | ||
{ | ||
"version":"1", | ||
"url":"https://www.example.com/gbfs/1/gbfs" | ||
}, | ||
{ | ||
"version":"2", | ||
"url":"https://www.example.com/gbfs/2/gbfs" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just a formatting note, can we add the spaces between the ":" and value here as well? Thanks! |
||
} | ||
] | ||
} | ||
} | ||
``` | ||
|
||
### system_information.json | ||
The following fields are all attributes within the main "data" object for this feed. | ||
|
||
|
@@ -235,6 +285,7 @@ Example: | |
{ | ||
"last_updated": 1434054678, | ||
"ttl": 0, | ||
"version": "1.0", | ||
"data": { | ||
"rental_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.
Is this "should" or "must?" If a producer does not provide LTS and the latest feed, are there any repercussions?
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.
This is framed as a "Best Practice" to work within the bounds of the authority of specification authors. This is a recommendation, not a requirement. Making any sort of requirement with repercussions is the domain of cities and other governments and/or bikeshare contract holders.
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.
A clarifying question: what does "It highly recommended that GBFS consumers support later releases." mean?