manifest.json: include area, country_code

[futuretap]

What problem does your proposal solve? Please begin with the relevant issue number. If there is no existing issue, please also describe alternative solutions you have considered.

As described and discussed in #520, this PR adds new area and country_code fields allowing consumers to select relevant feeds according to the user location. area is proposed as a GeoJSON MultiPolygon (instead of plain rectangles) since most stake holders seemed to prefer this format.

What is the proposal?

Add area and country_code to manifest.json.

Is this a breaking change?

• Yes
• No
• Unsure

Which files are affected by this change?

manifest.json

[CLAassistant]

All committers have signed the CLA.

[mplsmitch]

I'm not an expert on validation but it seems like not specifying a code would make things difficult. To validate an empty country_code you would need to verify that area does in fact span international borders. Maybe it would be better to require the use of a user-assigned 3166 alpa-2 code. We could choose one from the list and require it's use for any case where a system spanned international borders. Details on how that works here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#User-assigned_code_elements

[futuretap]

Both fields are OPTIONAL so I don’t see an issue if one of the fields is left out. Imo, an empty country code should be avoided. Instead it should be left out.

We could also allow multi-country polygons together with a country_code. In this case, both conditions have to be met, so the operating area equals the multi polygon intersected with the country area. Would you prefer this? It’s really an edge case that should rarely ever occur but the language should of course be clear.

[mplsmitch]

Both fields are OPTIONAL so I don’t see an issue if one of the fields is left out. Imo, an empty country code should be avoided. Instead it should be left out.

I totally agree. What I'm suggesting is that if I'm publishing a manifest.json list that includes a number of systems, each with it's own country_code, it might make sense to have a reserved code, say XX. This would be used to indicate a system that spans multiple countries in stead of having to write an exception for that one list item where the country_code field should be left out. That way we would avoid the possibility of an empty country_code and the file would still be valid.

We could also allow multi-country polygons together with a country_code.

As area is currently defined, I would assume this would already be allowed. There's nothing to indicate that area should be limited to a single country. So then the question is, if you have a multi-country polygon, which country code would you use with it?

This is all very much an edge case so I'm fine with leaving it as it's currently written. If it ever comes up in the future we can easily fix it.

[futuretap]

What I'm suggesting is that if I'm publishing a manifest.json list that includes a number of systems, each with it's own country_code, it might make sense to have a reserved code, say XX. This would be used to indicate a system that spans multiple countries in stead of having to write an exception for that one list item where the country_code field should be left out. That way we would avoid the possibility of an empty country_code and the file would still be valid.

We could allow JSON null for the country_code. I assume most parser implementations would resolve this to the same as leaving it out. Would be cleaner imo than specifying XX or multi or something similar.

[richfab]

A potential solution to avoid the conditional requirement could be to name the field country_codes and make it an array. So, for a system in a single country we would have "country_codes": ["DE"] and for a system that covers several countries "country_codes": ["DE", "FR"]. Looking forward to hearing your opinion.

[futuretap]

I’m open about making it an array. The only gripe I have is when a system is worldwide or covers a very large number of countries (are there such systems?).
Not sure though if it’s actually a problem. In systems.csv we have a single country code for ages and it seems to work well.

[richfab]

I hereby call a vote on this proposal. Voting will be open for 10 full calendar days until 11:59PM UTC on Monday, January 15, 2024.
Please vote for or against the proposal, and include the organization for which you are voting in your comment.
Please note if you can commit to implementing the proposal.

[tdelmas]

+1 From Fluctuo

[richfab]

Voting on this PR closes in 3 calendar days, at 11:59PM UTC on Monday, January 15, 2024. Please vote for or against the proposal, and include the organization for which you are voting in your comment.

[BredeD]

+1 from Entur

[richfab]

The vote remains open until quorum is met. Tagging recent contributors for visibility: @testower, @jkurzanski, @PierrickP, @cmonagle, @simonsolnes, @ezmckinn, @AntoineAugusti, @Cj-Malone, @ArashMansouri, @bdferris-v2, @HannesOlszewski.

Thank you for your involvement in the spec 🙏

[bdferris-v2]

I appreciate the updates based on my feedback. Unfortunately, Google is a +0 on this proposal. Which is to say, I don't think we have an specific qualms with it (especially after the updates), but we don't anticipate using it either. So deferring votes to those who actually would.

[richfab]

Given that there are at least 1 vote each from a producer (ENTUR) and a consumer (Fluctuo), the third vote can come from the Advocate (@futuretap).

reference

[futuretap]

Thanks, so +1 from Where To? / FutureTap.

[richfab]

With some delay on my side, this vote has now closed, and it passes!

Votes in favor:
Fluctuo (consumer)
Entur (producer)
Where To? (consumer)


There were no votes against.

This change will be part of v3.1-RC planned to be released in May, as per the version release cycle in the governance.

Thank you for your involvement in the GBFS spec 🙏