Are feed URLs required to end with ".json"?

[barbeau]

Reading the spec, I would assume that the URL endpoints that are defined in the spec (for example,
station_information.json) would always include the .json extension.

However, I see a number of feeds in the wild, including many in the systems.csv file in this repo, that don't include the .json extension on the end of the URL - for example:
https://gbfs.hopr.city/api/gbfs/8/free_bike_status

...instead of:
https://gbfs.hopr.city/api/gbfs/8/free_bike_status.json

The gbfs.json auto-discovery endpoint example listed here in the reference also doesn't include the .json file extensions on any of the listed URLs.

Additionally, many of these feeds have the auto-discovery feed as a root directory instead of with a gbfs.json endpoint - for example:
https://tor.publicbikesystem.net/ube/gbfs/v1/

...instead of:
https://tor.publicbikesystem.net/ube/gbfs/v1/gbfs.json

Example feeds with these properties:

• https://tor.publicbikesystem.net/ube/gbfs/v1/
• https://nicosia.publicbikesystem.net/ube/gbfs/v1/
• https://lou.publicbikesystem.net/ube/gbfs/v1/
• https://tuc.publicbikesystem.net/ube/gbfs/v1/
• https://gbfs.hopr.city/api/gbfs/8/

Questions:

1. Do URLs need to end with .json to officially conform with the spec?
2. Is the auto-discovery feed allowed to be a root directory instead of gbfs.json and still conform with the spec?

[maduprasPBSC]

For the PBSC cities above (Toronto, Nicosia, Lousville, Tucson), we support both access methods, with and without .json. The root auto-discover endpoint also supports gbfs.json in the latest version. For example Barcelona: https://barcelona.publicbikesystem.net/ube/gbfs/v1/gbfs.json. As the other cities are updated to the newer version, I will update the system.csv file to reflect the changes.

[jcn]

@barbeau Regarding both of your questions, it was never the intent to dictate the actual filenames, as I consider those to be an implementation detail of the provider. For example, I could see a provider potentially building the JSON files statically and letting something like S3 or a regular web server serve them up - in that case the server might require a json extension. On the other hand, if served dynamically, then the extension might not be required. Same goes for the auto-discovery URL. As long as it serves the auto-discovery file, the actual URL format should be irrelevant.

The feeds do have to be valid JSON though, so I would expect the servers to serve them with the correct content type: application/json though this isn't explicit in the spec (it's implicit in that the auto-discovery example includes the correct content type).

[barbeau]

Thanks @jcn, I was wondering if the filenames themselves were indeed flexible.

To make things a little clearer for consumers, I'd suggest the following:

1. Feed URLs must conform to file names in the spec unless auto-discovery gbfs.json is provided
2. A set of keys should be well-defined for gbfs.json name field that corresponds to each of the feeds in the spec. These keys seem to be implied but never explicitly stated in the current spec, as far as I can tell. This would allow producers to then use any URL as long as it's keyed correctly in the gbfs.json autodiscovery and consumers can be confident that as long as the key matches they will be pulling the correct feed.

[jcn]

I propose we be even more explicit and just make the auto-discovery file required. Every provider in the systems.csv file has an auto-discovery URL anyway as far as I can tell.

We would still need to make the keys explicit, which would be, I'd imagine, the base file name of each feed.

[barbeau]

@jcn Requiring auto-discovery file and using base file name as explicit key sounds good to me.

[antrim]

@jcn, @barbeau : Should this be advanced to a pull request, or do you think more research and feedback is needed?

[barbeau]

@antrim I think the proposal itself can be advanced as-is. However, to be most useful I think it requires versioning in the spec. Without an explicit version in the auto-discovery URL response, apps won't know if a particular feed has the standardized keys to be able to find the rest of the endpoints.

[jcn]

@antrim @barbeau Agree that this should be advanced as is. Regarding versions, perhaps we can move the discussion to #163 (which seems like a good a place as any to discuss this) but I propose we should take this and all other "clarifying" spec changes and release a 1.1.0 as a base starting point for future enhancements.

[evansiroky]

We at IBI also just noticed this oddity about the HOPR feed. We support advancing this proposal to get clarification.

[heidiguenin]

Now that we're actually moving toward a versioning scheme and then likely making use of it right away with #147, @jcn's suggestion that we include this in a bundle is the direction we're hoping to go. Seems like this one has consensus, too. @barbeau, want to open the PR?

[barbeau]

@heidiguenin Yes, I'll work on a proposal for this.

[barbeau]

I've opened a proposal at #189 for review.

Comments welcome!

[heidiguenin]

Closing this issue now that PR is open.