Skip to content
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.

Sign up for GitHub

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

Jump to bottom

GBFS documentation versioning and and feed conformance #188

Merged
merged 7 commits into from
Nov 25, 2019
Merged

GBFS documentation versioning and and feed conformance #188

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
29db809
Spec versioning proposal
antrim Nov 6, 2019
ea50d81
Corrections to initial commit
antrim Nov 6, 2019
8cf699e
Improvements & clarifications
antrim Nov 7, 2019
d746a64
corrections
antrim Nov 7, 2019
1397ac4
new examples, URL scheme
antrim Nov 12, 2019
fc77ed2
minor clarification to examples
antrim Nov 18, 2019
c2dc3d6
Minor update to example data
antrim Nov 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions README.md
View file
Open in desktop
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. A git tag in the form of `X.Y` establishes semantic versions. Multiple changes (commits) may be batched into a single new release.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that git tags technically have to start with a letter, so the tag will be vX.Y where the version name itself will be X.Y

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed


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
62 changes: 58 additions & 4 deletions gbfs.md
View file
Open in desktop
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. 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.

Copy link
Contributor

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?

Copy link
Contributor Author

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.

Copy link
Contributor

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?

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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could make this required in a future backwards compatibility breaking MAJOR change.

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.
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",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency with the rest of the documentation, wherever new JSON fields were added, can we add a space after the :?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Changed.

"data": {
"name": "Citi Bike",
"system_id": "citibike_com"
Expand All @@ -120,41 +136,78 @@ _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.0/en/system_information"
},
{
"name": "station_information",
"url": "https://www.example.com/gbfs/en/station_information"
"url": "https://www.example.com/gbfs/1.0/en/station_information"
}
]
},
"fr" : {
"feeds": [
{
"name": "system_information",
"url": "https://www.example.com/gbfs/fr/system_information"
"url": "https://www.example.com/gbfs/1.0/fr/system_information"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we going to remain silent on how versioning should be handled in the URL path?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think? Should we offer a recommendation? As this is written, it's up to the discretion of the feed producers. The examples offer suggestions.

Copy link
Contributor

@jcn jcn Nov 7, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should state that a URL must never change its major version. For example, if a feed doesn't want to include a version in the path, that's fine, but it must not change from v1 to v2 ever.

This actually brings up another question - can a feed change from 1.0 to 1.1? Technically this should not break anything, and it would mean that publishers could have, say, https://www.example.com/gbfs/1/fr/system_information for their feed that conformed to the 1.X spec. Would this be confusing for consumers?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One challenge for dictating versions in URL paths is that it could conflict with existing versioning schemes or numbers used by producers in URL paths. For example, HOPR currently uses integers in the URL path to identify systems - https://gbfs.hopr.city/api/gbfs/6 vs https://gbfs.hopr.city/api/gbfs/8.

So there could be significant backwards compatibility concerns.

If we require the auto-discovery file (see proposal at #189), I'm inclined to let producers manage their own URL paths.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jcn I just pushed a change that responds to what you pointed out. Please let me know what you think…

},
{
"name": "station_information",
"url": "https://www.example.com/gbfs/fr/station_information"
"url": "https://www.example.com/gbfs/1.0/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": {
[
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be

"versions": [

(you're missing the key name)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Fixed.

{
"version":"1.0",
"url":"https://www.example.com/gbfs/1.0/gbfs"
},
{
"version":"1.1",
"url":"https://www.example.com/gbfs/1.1/gbfs"
},
{
"version":"2.0",
"url":"https://www.example.com/gbfs/2.0/gbfs"
}
]
}
}
```

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

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