Use RFC 3339 format for timestamps

[jcn]

As per a comment from Tom Brown in the original spec, we propose that timestamps be changed from POSIX time to RFC 3339 for potential human-readability and clarity (to avoid millisecond confusion).

Furthermore, I would propose that the time zone always be set to "Z" (i.e. UTC) to further prevent confusion.

i.e. 2016-01-13T21:19:33Z instead of 1452719973

[fruminator]

Yes. Nothing worse than implicit time zones.
On Jan 13, 2016 9:08 PM, "Jesse Chan-Norris" notifications@github.com
wrote:

As per a comment from Tom Brown in the original spec, we propose that
timestamps be changed from POSIX time to RFC 3339
http://tools.ietf.org/html/rfc3339 for potential human-readability and
clarity (to avoid millisecond confusion).

Furthermore, I would propose that the time zone always be set to "Z" (i.e.
UTC) to further prevent confusion.

—
Reply to this email directly or view it on GitHub
#9.

[jcn]

@fruminator And to be clear, the proposal here is mostly about moving from POSIX time (1452719973) to RFC 3339 ("2016-01-13T21:19:33Z"). POSIX time on its own would also avoid time zone problems.

[dsgermain]

Strongly agree with this one!

[jasongdove]

This makes sense.

[mdarveau]

I like POSIX time. I think it's less error prone since it forces the consumer to think about the timezone. One could simply parse the RFC 3339 date without knowing what the Z means and would end up with invalid local dates.

There are implementations of the GBFS feed deployed and IMHO this is a style change and does not justify a breaking change.

[dsgermain]

APIs can (and should) be versioned so that you don't break existing users. If the coder doesn't know about "Z", they'll ignore all other time zones as well. That is not a valid argument IMHO.

[mdarveau]

+1 on the need of versioning.

Fair point that if the coder does not know about Z he is likelly not familiar with date/timezone manipulation. The thing with POSIX time is that it does not look like a date so you don't have much choice when you convert it to specify a timezone or the lib will use local time afterward for display.

The question is: does it make a enough of a difference to justity a new version?

[jcn]

My reason for making the change would be for developer readability. I like the idea that you could eyeball the feed and understand what's going on. JSON overall is pretty readable, and I feel like the POSIX dates just force people to have to do the conversion even to do simple sanity checks.

[jcn]

@mdarveau Also, how many GBFS consumers are there in the world right now, considering this spec was still technically in draft form until we published it here? In the interest of overall readability I feel like this change and the boolean change (#10) could be considered the last major updates before a true v1.

[dsgermain]

I agree that now is the time vs later, as these changes will become incrementally harder to push through and have adopted. I'll comment on the versioning scheme in #15.

[mdarveau]

We (8D) used to publish formatted dates and found that 3rd party had trouble handling the timezone portion without issues. When we switched to POSIX, they had trouble figuring the conversion (especially the second vs millisecond part) but that was handled during integration instead of a bug fix in production. It's been a while though and everything was XML, not JSON.

I'm -1 on this one but if the group prefer RFC 3339 vs POSIX then so be it. I don't have more arguments :-)

[fruminator]

Yeah, I think we can make these kinds of changes now and squeeze into V1.
On Jan 15, 2016 4:01 PM, "Jesse Chan-Norris" notifications@github.com
wrote:

@mdarveau https://github.com/mdarveau Also, how many GBFS consumers are
there in the world right now, considering this spec was still technically
in draft form until we published it here? In the interest of overall
readability I feel like this change and the boolean change (#10
#10) could be considered the last
major updates before a true v1.

—
Reply to this email directly or view it on GitHub
#9 (comment).

[cubbi]

We (SoBi) already have some integrations (more than 1) running on GBFS and would prefer not to change it in V1 - so we will not break those integrations. Also I remember talking about this back in October, and we decided to stay with POSIX - that was a part of discussion what TZ format to use. I guess we have to first solve versioning issue before making this change.

[jcn]

@cubbi Have these integrations been published widely yet, and would it be a huge problem for you to make this change and the change proposed in #10 in the next update of your code? I do understand that it would be a code change change, but given the benefits, I'd prefer to officially "launch" the spec with these two modifications rather than requiring ALL future producers/consumers to handle the differences between the formats.

i.e. I'd prefer not to get locked into a legacy format before the spec has even been properly released in the wild. If you're arguing that POSIX is a better solution, then that's one thing, but it seems like the consensus is around RFC 3339 (and FWIW I was doing some searches around other public APIs and most of them seem to be settling on more human-readable formats vs POSIX timestamps).

[cubbi]

@jcn It's not a problem for us. It will be problem for some of the partners that are live with some of their deployments. We would have to give them a notice. Also our understanding was that all the vendors agreed to the format and we set a deadline for implementation at the end of the year. That's why we have been promoting GBFS actively since November.

I am not arguing that one is better over other, I see benefits of this change, but again, it's not what we agreed on originally.

[fruminator]

Marcin, thanks for that explanation.

Tons of credit to you for having gone live so quickly on this. But moving
forward before a spec is finalized always comes with a bit of its own
risk. This seems like a very easy thing for you and the initial clients to
manage -- they can have some code that handles POSIX or RFC#### which would
allow you to change smoothly.

If this is any of the big multi-modal app developers, I'm happy to plead on
your behalf for the flexibility as we iterate through the early versions of
the spec. I really do agree that having JSON API's be very human readable
-- I find that it makes debugging and development move much more quickly
which brings more developers and reinforces the adoption of the standard.

Thanks
Mike

Michael Frumin
Vice President, Technology
Motivate
michaelfrumin@motivateco.com
p: 347-916-0724
m: 917-669-9070

On Tue, Jan 19, 2016 at 10:20 AM, Marcin Pyla notifications@github.com
wrote:

@jcn https://github.com/jcn It's not a problem for us. It will be
problem for some of the partners that are live with some of their
deployments. We would have to give them a notice. Also our understanding
was that all the vendors agreed to the format and we set a deadline for
implementation at the end of the year. That's why we have been promoting
GBFS actively since November.

I am not arguing that one is better over other, I see benefits of this
change, but again, it's not what we agreed on originally.

—
Reply to this email directly or view it on GitHub
#9 (comment).

[dsgermain]

+1 with Frumin.

Cheers,
David

[cubbi]

@fruminator I do not agree on the early adopter part. All our integrations have been implemented AFTER NABSA approved and announced format. This change, as well as, #10 introduce a semantic change which does not bring a lot of value to the app developers. SoBi will keep it as it's now, and if this change will be approved, we might update it in the future.

[mdarveau]

It was my understanding as well that we all agreed in Chicago. Sobi, 8D and possibly others have implemented V1 based on the fact that this was an approved spec.

My suggestion to move forward is to leave V1 as-is and discuss then accept/reject those changes (boolean, date, ...?) for V2 once we agree on the versioning scheme. Other vendors could wait until V2 to implement GBFS if they want to.

[mplsmitch]

I would echo what @cubbi and @mdarveau said, it's not a case of early adoption - we gave the go-ahead to implement back in November in return for a commitment to get it done by end of year. In fact we called it V1.0 in the Google doc revision history when NABSA adopted it on Nov 5. Bcycle is also done and feeds are running in a bunch of cities. I'm all for the suggested changes but we need to develop some reasonable rules around versioning so developers aren't all pissed. Maybe we can take this up under #3

[fruminator]

Jesse and I chatted off line and yeah we are OK without making these
optimizations. It's the price we pay for moving very quickly.

Thanks everyone, a very healthy conversation!
On Jan 21, 2016 12:50 PM, "Mitch Vars" notifications@github.com wrote:

I would echo what @cubbi https://github.com/cubbi and @mdarveau
https://github.com/mdarveau said, it's not a case of early adoption -
we gave the go-ahead to implement back in November in return for a
commitment to get it done by end of year. In fact we called it V1.0 in the
Google doc revision history when NABSA adopted it on Nov 5. Bcycle is also
done and feeds are running in a bunch of cities. I'm all for the suggested
changes but we need to develop some reasonable rules around versioning so
developers aren't all pissed. Maybe we can take this up under #3
#3

—
Reply to this email directly or view it on GitHub
#9 (comment).

[jcn]

I've added a 2.0 milestone for this and #10.

I suspect that these will not actually make sense to implement as the inertia to change existing systems will be too great, but I will keep the issues open in case future adopters of the spec on both sides feel strongly about it.

[stale]

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