informing consumers about inactive markets

[ArashMansouri]

Have you read our FAQ? It’s possible your question can be answered there!

If you are new to the specification, please introduce yourself (name and organization/link to GBFS). It’s helpful to know who we're chatting with!

Hi,
My name is Arash Mansouri and I'm an engineering manager at Lyft.

What is the issue and why is it an issue?

I'm opening this issue as we are seeking guidance on how one would go about informing consumers of a GBFS feed about the fact that a particular market is no longer active. We would expect this information to fit into the system_alerts.json file as it is supposed to be used for temporary shut-downs, but wanted to seek guidance on whether that is appropriate.
Questions:

• Can that file be used for permanent shut-downs, perhaps with the end field under times being omitted?
• Do you have any other recommendations for how one would notify consumers of this, without shutting the feed down all together which might lead to something breaking on the consumer's side?
• Would it be possible to perhaps add a field to that file distinguishing a temporary shutdown from a permanent one?

Please describe some potential solutions you have considered (even if they aren’t related to GBFS).

We have considered using the system_alerts.json as described above.

Is your potential solution a breaking change?

• Yes
• [ ✔️ ] No
• Unsure

[mplsmitch]

This has come up more than one in the past so I'm open to suggestions as to what sort of guidance we should add to the specification.

Here's my take:

Since GBFS is a real-time specification, it's assumed that when a service is no longer available (permanent shutdown) the feed would no longer be published.

If the market is no longer active, there would be no real-time information to deliver to the data consumer so breaking a downstream application shouldn't be much of an issue since a lack of real-time data would mean it's essentially broken anyway.

What's been recommended in the past is to stop publishing the feeds and use a helpful http status code and text for example 410 service no longer available ... . If you know that a service will be ending soon you could randomly fail some requests to deliver an appropriate http status code message prior to the feed going off line.

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_client_errors

Continuing to publish empty feeds when a service has permanently shutdown can lead to confusion as to whether the service is still operating. It also makes it difficult to keep the systems catalog up to date because it's assumed that if the feeds return 200 vs 4xx then the service is still active.

When a service is temporarily unavailable, for example a seasonal shutdown, then feeds should continue to be published showing that the service still exists, but there are no vehicles available for rent.

[mwillmott]

That's helpful @mplsmitch - i think using an HTTP status code longer term after the shutdown makes a lot of sense. A question in my mind is whether there's an argument for handling the period directly before and after the shutdown at all differently?

e.g. in the weeks (or days) leading up to a shutdown, should operators publish this info in the feed? Is there some way that this could be done to help alert 3rd party consumers as to the upcoming shutdown?

Similarly, in the period directly after is it useful to be more explicit to consumers about the recent shutdown (maybe communicating the date at which point operations ceased?)

I wonder there's some best practice guidance that looks something like "start publishing X info as soon as you know about an upcoming shutdown, continuing publishing Y info for (one, two, three?) months after the shutdown and after that ideally return an http status code for that feed in the long term"

[mplsmitch]

@mwillmott great question

e.g. in the weeks (or days) leading up to a shutdown, should operators publish this info in the feed? Is there some way that this could be done to help alert 3rd party consumers as to the upcoming shutdown?

Currently what's supported is the setting of an end date for the service. This can be done in systems_calendar.json for versions <v3.0 and in system_information.json via the opening_hours field for v3.0 going forward. These fields are intended as the date the service is available to users (when vehicle are available for rent) so they don't really do what you're looking to do, which is indicate when data feed will no longer be available for consumption by 3rd parties. That said, letting end users know that vehicles will no longer be available for rent in the future should still be a priority. As Arash said above, this is also something that could be communicated to users via system_alerts.json.

This doesn't exactly do what you're asking and one place this doesn't work is in a situation like you have in Minneapolis where the system went into seasonal shutdown and now it's not coming back. For that we would need to add something. I would suggest adding a new field to system_information.json

Field	REQUIRED	Type	Defines
end_date	OPTIONAL	Date	Date after which this data source will no longer be available to consuming applications. This OPTIONAL field SHOULD be used to notify 3rd party data consumers when a service is planning a permanent (non-seasonal) shutdown. Publishers SHOULD include this date in their feeds as soon as they know of an impending shutdown. Publishers SHOULD continue to publish feeds for 30 days following a permanent shutdown after which they SHOULD return a helpful http status code and text for example 410 service no longer available ... for all feed endpoint URLs.

Would this work for you?

Also, on the same topic, I'm guessing this probably isn't in your wheelhouse but it sure would be nice if this site could get updated with the current status.

[mwillmott]

I like that proposal @mplsmitch - i think that neatly covers everything we've spoken about.

I'll reach out to the right team to get that website updated.

[josee-sabourin]

Closing this since #497 has been opened to address this.