Add guidance about making suggestions

[fkh]

If someone has a suggestion to improve GBFS, what is the process for adding a suggestion? Beyond adding an issue to the repo, what should be included in the description?

Perhaps separately, or not, what is the process for improving and modifying the spec?

[jcn]

I would love to hear from people who have been part of the GTFS process as outlined here: https://developers.google.com/transit/gtfs/changes

This seems like a reasonable approach and I would suggest that we mimic it with the exception being that the first step, rather than taking place on the mailing list, could take place in an issue tagged "proposal" in Github.

Thoughts?

[mdarveau]

It seems like a lightweight and reasonable approach.

The "Note that the GTFS readily allows for extensions to the format through the addition of extra columns and files that are ignored by the official parsers & validators, so proposals can be easily prototyped and tested on existing feeds." part is interesting. I don't see any mention about extensions in the GTFS feed but since it's CSV, I assume one could simply add more columns.

Should we declare extension points in the GBFS feeds? Maybe something as simple as "Any JSON node can contain an 'extensions' key holding vendor specific or GBFS proposal proof of concept extensions.".

For example:

{
  "last_updated": 1434054678,
  "ttl": 0,
  "data": {
    "rental_hours": [
      {
        "user_types": [ "member" ],
        "days": ["sat", "sun"],
        "start_time": "00:00:00",
        "end_time": "23:59:59",
        "extensions": {
          "some_new_info": {...}
        }
      }
    ],
    "extensions": {
      "some_new_info": {...}
    }
  }
}

[fruminator]

so, I think the GTFS modification process has actually been pretty slow. I
think we are going to need something that moves more quickly as we have
just started this process and we know bike share moves much faster as an
industry than transit.

in terms of GTFS allowing for new columns in CSV, I think the philosophy is
this -- add things to your data as long as it doesn't break existing
feeds. The analogy in JSON is just to add new keys/attributes to whatever
existing JSON objects you want. Then people start using it, and when those
new attributes become "official" everyone's code already works.

from my experience, something like "extensions" is more for "local
extensions" that are specific to a particular application but that you're
not necessarily expecting will become part of the more global standard.

Thanks
Mike

Michael Frumin
Vice President, Technology
Motivate
[email protected]
p: 347-916-0724
m: 917-669-9070

On Tue, Jan 19, 2016 at 9:16 AM, Manuel Darveau [email protected]
wrote:

It seems like a lightweight and reasonable approach.

The "Note that the GTFS readily allows for extensions to the format
through the addition of extra columns and files that are ignored by the
official parsers & validators, so proposals can be easily prototyped and
tested on existing feeds." part is interesting. I don't see any mention
about extensions in the GTFS feed but since it's CSV, I assume one could
simply add more columns.

Should we declare extension points in the GBFS feeds. Maybe something as
simple as "Any JSON node can contain an 'extensions' key holding vendor
specific or GBFS proposal proof of concept extensions.".

For example:

{
"last_updated": 1434054678,
"ttl": 0,
"data": {
"rental_hours": [
{
"user_types": [ "member" ],
"days": ["sat", "sun"],
"start_time": "00:00:00",
"end_time": "23:59:59",
"extensions": {
"some_new_info": {...}
}
}
],
"extensions": {
"some_new_info": {...}
}
}
}

—
Reply to this email directly or view it on GitHub
#3 (comment).

[eric-poitras]

I disagree with this statement: "add things to your data as long as it doesn't break existing
feeds." as the standard should be allowed to add new fields without fearing to break existing non-standard extensions implemented into the wild.

If you take HTML5, it allows to define custom attributes as long as it begins by "data-". Same login in css where vendor agreed to prefix their extensions with '-' like '-ms-'.

We should decide a way so vendor could add extensions without hindering the main standard to evolve.

[mdarveau]

For the record, we have our first extension to the feed.

In station_information.json we will add:

• eightd_has_key_dispenser : Boolean: Indicates if there is a bike key dispenser at the station.

In station_status.json we will add:

• eightd_has_available_keys : Boolean: Indicates if there are bike keys remaining at the station.

I suggest we add a "vendor specific" extension page in this repo to document them.

[jcn]

@mdarveau I'm curious why these are vendor-specific extensions. It seems like it could just as easily be the generic has_key_dispenser and has_available_keys and be more flexible.

[fruminator]

@mdarveau care to comment on @jcn comment/suggestion here? I agree with him that there's no reason this needs to be named in an 8D-specific way.

[jcn]

@mdarveau I am concerned about adding extensions throughout the feed for fear of making things a bit too messy. And to dig into @eric-poitras's point a bit more, tagging all non-standard extensions with ext_ seems like it would make adoption and integration a bit more complicated.

If we had ext_has_key_dispsenser and it was decided that it would be added to the spec as has_key_dispenser then would we expect all existing clients to have to change the key they're looking for (or support 2 keys for the same item) as long as old "versions" of the API were out there? This seems like a burden and I'm not sure whether we would be able to iterate versions of the API fast enough to support new extensions.

To me, adding new keys without a set prefix might work, but perhaps with @mdarveau's suggestion that the extension is documented (I suggest on a wiki page on the GBFS repository).

[mdarveau]

I support @eric-poitras statement that we should not encourage extensions to be added without some namespace. I like the HTML5 approach (or should I say W3C?) where extensions can be added without notice as long as there is a vendor specific prefix. This allows quick addition to the feed without prior approval all members. Then extensions are proposed/discussed and consumers can migrate to the official one.

At this point, I think most extensions will be added and consumed by applications "close" to the supplier of the feed for new/unexpected features. If/when proven useful, extensions will be added to the spec and consumed by others. If they decide to use the extension with the vendor prefix, they should be careful to follow how it evolve.

[cubbi]

I agree with @mdarveau. We should just make sure that all extensions have prefix which clearly states that this is variable is vendor specific one - maybe all prefixed with underscore or "-" as it was suggested above?

[fruminator]

fair enough!

Michael Frumin
Vice President, Technology
Motivate
[email protected]
p: 347-916-0724
m: 917-669-9070

On Wed, Mar 16, 2016 at 4:55 AM, Marcin Pyla [email protected]
wrote:

I agree with @mdarveau https://github.com/mdarveau. We should just make
sure that all extensions have prefix which clearly states that this is
variable is vendor specific one - maybe all prefixed with underscore or "-"
as it was suggested above?

—
You are receiving this because you commented.
Reply to this email directly or view it on GitHub
#3 (comment)