Canonical URL for v1 spec?

[tmontes]

Hello all,

I'm currently evaluating a project where GBFS data will be sourced from multiple providers. Having found references to versioning in #9, #15, #92 and #93 at least, I understand that versioning is something that people who've been working on this have on their minds: mostly at the feed level, hardly at the "document level", if I may call it so.

I couldn't, thus, easily determine a "canonical URL" for the v1 spec document:

• https://github.com/NABSA/gbfs/blob/master/gbfs.md will change as newer versions are merged in.
• https://github.com/NABSA/gbfs/blob/f4bfc84b8d6af4f9dfcf9b2e98073fe57e61efef/gbfs.md is the best I could come up with which, honestly, is both ugly (but irrelevant) and maybe not based on the correct commit (important).

In #9, @jcn said:

While we've said that we would version the spec in the repository via git tags, we did not (...)

That sounds like a useful approach.

AFAICT, the repo isn't currently tagged. Has any decision been made in this context? Are the formal spec versions published somewhere else, outside of GitHub? What would be the "canonical URL for version X.Y.Z of the spec"?

Thanks in advance.

[jcn]

@tmontes As of now, everything is still technically unversioned (or perhaps v1.0), and while there are some proposed changes that will change/clarify the spec moving forward in a 1.1 or 2.0, these haven't been formally adopted (#94 an #92 come to mind specifically).

So at this point the answer is that we don't actually have canonical versions yet with the larger issue that many of the providers are inconsistent with their data even in the presence of the spec (i.e. not precisely conforming). Were there specifics where a version would help with your feed parsing?

[tmontes]

@jcn, thanks for the quick feedback.

The concern with this issue stems from my due diligence phase in evaluating a project I'm probably about to start working on. I've been told we need to process GBFS information feeds per <link to this repository> from the prospect client.

I've prototyped some code and found no major troubles so far.

I'm just looking into something that, at some point in the near future, I can refer to to formally state this code processes GBFS feeds per <this specification> where <this specification> would be locked to a given revision of this spec.

In short:

• If what's currently on master is version 1.0.0, maybe it could indeed be git tagged as such: that would be useful for my purpose and, I suppose, useful in current/future discussions for everyone else.
• Otherwise, if the issues you mentioned may become integrated into version 1.0.0 (and not 1.0.1, 1.1.0, or some other), then, when the time comes, I'll probably need to link to a specific commit hash on this repository, like the one I linked to in my initial comment.

Can you please clarify which of these is true, as of today?

On a tangential note: I believe having JSON Schema documents along with the spec would be valuable. While the current prose defines both structure and semantics, I'd argue that publishing such complementary documents along with the spec would help disambiguate structure while also simplify the automation of structural validation. Has anyone thought of this before?

[heidiguenin]

We're picking up the versioning conversation in earnest again over at #15 - can we move any more feedback there and close this issue out?

@jcn @tmontes

[tmontes]

@heidiguenin, thanks for chiming in. Sure, let's move the conversation to #15.
Closing now. :)