diff --git a/README.md b/README.md index bb7cd8f8..ad7e62b0 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,26 @@ The general outline for changing the spec has 4 steps: 3. Find at least one GBFS producer to implement and test the proposed change. 4. Submit a final request-for-comments on the proposed change to the issue discussion. If no outstanding issues are identified after one week’s time, and there is general agreement that the proposed change is worthwhile and follows the GBFS guiding principles outlined below, the proposal will be officially adopted. +## Specification Versioning +To enable the evolution of GBFS, including changes that would otherwise break backwards-compatibility with consuming applications, GBFS documentation is versioned. Semantic versions are established by a git tag in the form of `vX.Y` where `X.Y` is the version name. Multiple changes (commits) may be batched into a single new release. + +A whole integer increase is used for breaking changes (MAJOR changes). A decimal increase is used for non-breaking changes (MINOR changes or patches). + +Examples of breaking changes include: + +* Adding or removing a required endpoint or field +* Changing the data type or semantics of an existing field + +Examples of non-breaking changes include: + +* Adding or removing an optional endpoint or field +* Adding or removing enum values +* Modifying documentation or spec language in a way that clarifies semantics or recommended practices + +### Version Release Cycles +* There is no strict limitation on the frequency of MAJOR releases, but the GBFS community aims to limit the MAJOR releases to 2 or fewer every 12 months. To limit releases, breaking changes can be batched together. +* MINOR changes may be applied at any time. There is no guideline to limit the number of MINOR changes. MINOR changes may be batched or released immediately, at the discretion of the pull request author and advocate. +* GBFS documentation will include a designated long-term support (LTS) branch. The LTS branch would maintain its LTS status for at least 2 years, after which a new LTS release and branch would be designated. The LTS branch will be determined according to the GBFS voting process. Non-breaking changes (MINOR) will be applied to the LTS branch when relevant. ## Extensions Outside of the Specification ## To accommodate the needs of feed producers and consumers prior to the adoption of a change, additional fields can be added to feeds even if these fields are not part of the official specification. It's strongly recommended that these additional fields be documented on the wiki page in this format: diff --git a/gbfs.md b/gbfs.md index 65336087..4b05445c 100644 --- a/gbfs.md +++ b/gbfs.md @@ -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. 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,22 +136,24 @@ _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" } ] }, @@ -143,11 +161,11 @@ Example: "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" } ] } @@ -155,6 +173,38 @@ Example: } ``` +### 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" + } + ] + } +} +``` + ### 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": [ {