Skip to content

Commit

Permalink
GBFS documentation versioning and and feed conformance (#188)
Browse files Browse the repository at this point in the history 
(Passed with 6 votes in favor)
* Process to version GBFS documentation (breaking + non-breaking changes)
* Spec addition to include GBFS version info
  • Loading branch information
Aaron Antrim authored Nov 25, 2019
1 parent df473ca commit 44c8688
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 4 deletions.
20 changes: 20 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
59 changes: 55 additions & 4 deletions gbfs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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"
Expand All @@ -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"
}
]
}
}
```

### system_information.json
The following fields are all attributes within the main "data" object for this feed.

Expand Down Expand Up @@ -235,6 +285,7 @@ Example:
{
"last_updated": 1434054678,
"ttl": 0,
"version": "1.0",
"data": {
"rental_hours": [
{
Expand Down

0 comments on commit 44c8688

Please sign in to comment.