Specification proposal: Use IRIs instead of URLs

[simonsolnes]

When providing URLs for privacy policy, logo link, and similar, it can be the case that special characters are needed. In Norwegian, 'terms' is 'vilkår' and for 'policy', 'erklæring' can be used.

It's much easier to read
https://example.no/personvernerklæring than
https://example.no/personvernerkl%C3%A6ring

The solution to this is to allow for IRIs in the specification.

IRIs are supported by all web-browsers and is of course supported by the feed provider if they provide the IRI.

This is not a breaking change since IRIs is an extension of URL
As @futuretap mentioned, this will actually be a breaking change

[richfab]

Hi @simonsolnes and welcome!
Thank you very much for this contribution.
I am curious to know what other GBFS producers and consumers think about IRIs. Feel free to participate in this discussion if have an opinion on this topic!

[futuretap]

I'm against this proposal. GBFS is primarily made for machines, not humans. Depending on the consumer implementation URL parsing might fail, so this is a breaking change. If there would actually be the need to display any URL to the user, it’s easy to convert the URL-encoded characters back to display characters.

[derhuerst]

I think one could argue that not using IRIs leads to unintuitive behaviour for developers implementing GBFS, given that –even though this is technically inaccurate/wrong – most devs nowadays assume Unicode support when hearing the term "URL".

But I think @futuretap makes a very valid point about the proposed switch to IRIs being a breaking change!

[richfab]

Tagging recent contributors for visibility: @cmonagle @viestat @ArashMansouri @AntoineAugusti @ezmckinn @fbouchPBSC @Carl-NM @bdferris-v2 @kulovan @gajayraghav @testower @hynick4 @PierrickP @tdelmas @tobsesHub @tstrubel @HannesOlszewski @leonardehrenfried

[ezmckinn]

I support this proposal, largely in the interest of keeping the standard legible for humans. As a Product Manager sharing URLs with other humans, I value having something easy to read and explain — and to the extent we think of GBFS as an "open data" standard, it's worthwhile to keep it user-friendly for developers who use any alphabet.

If I particular publisher of GBFS feeds wants to use IRIs, the standard should not forbid it. IRIs may prove unpopular among aggregators who want to ingest that standard — but in that case, either the publisher of IRIs can revert to URLs or the aggregator can choose to support IRIs. The free market of publishers and aggregators will convene around the optimal solution.

The role of GBFS is to support interoperability, so a change that better supports languages besides English seems aligned with the mission (and the platforms who don't want to use IRIs, don't have to).

[PierrickP]

Agree with @futuretap . I'm against this change

• keep it for machine (GUI tools for GBFS exists)
• may occur bug on old system

[AntoineAugusti]

I'm against this change. GBFS is primarily made for machines, not humans.

• Humans involved with GBFS should already be familiar with JSON, APIs, foreign keys etc.
• If producers care about human-readable URLs they are in control of that
• GBFS endpoints are in English: free_bike_status, station_information etc.

[simonsolnes]

Thank you for providing your feedback, although I disagree with some arguments, we are all working together to make GBFS better.

I'd like to address some arguments

Argument for: Developer assumption

I think @derhuerst has a strong point that many developers do subconsciously assume URLs to be IRIs

I think one could argue that not using IRIs leads to unintuitive behaviour for developers implementing GBFS, given that –even though this is technically inaccurate/wrong – most devs nowadays assume Unicode support when hearing the term "URL".

IRIs has silently replaced URLs overall in APIs, websites and the like

Argument against: Machine readable

IRIs are specifically made for machines just like URLs, so I don't understand this argument.
I think what you are actually arguing against is a breaking change, not IRIs itself.

Arugment against: GBFS endpoints are in English

• There are English speaking countries that have place names, company names, and words in the dictionary that contain non-ASCII characters
• The API allows for different languages

Argument against: The specification is already technical with JSON, APIs etc

• JSON is made for humans and machines. If human readability wasn't a priority we would use some other format that would save more network traffic

[testower]

I don't think this is worth it due to lack of (computer) language support. Java does not support it which leads to having to use plain Strings and adding custom validation for it. I imagine it will be similar in other languages.

[derhuerst]

@testower So what's the status quo for existing GBFS tools? Process the URLs as URLs, even though some people may expect them to be IRIs – "This field likely works like the address bar in the browser." –, and therefore allow subtle bugs with non-ASCII IRIs?
If we decide to keep allowing URLs only (which I advocate against), then we should clearly document the implications to GBFS adopters, in a language that less technical people understand, and validate new contributions to systems.csv.

[testower]

I can only speak for the tools I use myself. Even though the "iri" format exists in json schema draft-07, the pojo generator maps this to String type in java, whereas it maps "uri" to java.net.URI. There is a IRI type in Java, so the first hurdle for me would be to get the pojo generator (which I don't maintain) to map iri format to IRI type. What other complications await further down the line and in other languages is hard to predict.

So what I'm saying is that it's probably not impossible to get done, but I don't really see it as important enough to be worth the hassle.

[futuretap]

Swift URL, or precisely the Apple Foundation API, supports ASCII URLs only (until iOS 16). The same is true for Ruby URI and many other languages. So I strongly advise against using IRIs in APIs. Instead, the URL representation should be used.

Wherever URLs are displayed to the user, they could of course be displayed as IRIs. That's what browsers do since ages.

[mobilitydataio]

This discussion has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.

[derhuerst]

still relevant

[mobilitydataio]

This discussion has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.

[derhuerst]

still relevant

[futuretap]

Please create a PR and ask for a vote. Just defending staleness by posting "still relevant" doesn't help anyone. I'm against this, as written above, but let the community decide!

[fredericsimard]

@richfab I'll let you handle this one.