THIS! Not having a defined Date format has caused so much confusion with consumers of our API since every json API might have a different ISO date format (or some homegrown madness).

In APIs I've integrated in recent years, I've seen:

1. ISO UTC 2. ISO local 3. Epoch 4. 2018-04-20 5. Jan 01 2016 11:58am

Probably others that I can't recall. It's a damn mess.

PHP-s strtotime() will probably handle them all, even though it will make you cringe a bit.

I never understood why simple integer unix timestamps are not more prevalent in API-s? Or some monotonic count from any reasonable epoch, depending on the context. How many APIs really have to ever return dates predating unix?

`/Date(1234567890)/`

That will probably cause a twitch to any dev that used Asp.NET up until a few years ago.

I had to deal with that two weeks ago. Cringe.

I’m twitching away...

Wow :(

To be fair, 1, 2 and 4 are all just ISO.

That's true. But 2 is substantially less useful than 1 and I encountered 4 mixed with 3.

Why wouldn't you just use epoch time?

aside from the other issues mentioned here, alternative encodings like ISO8601 and others are human-readable and human-editable

Epoch doesn't carry timezone information.

And it better not. Timezone information has nothing to do in a timestamp.

A timestamp is a point in time, whatever the time is in Paris or Tokyo. It is an abstract value and it is way better this way.

A timezone is a filter through which you display your timestamp, and it tells you what your local time was when that timestamp occurred.

So yeah, always store and exchange time information as timestamps. Timezone is extra styling information, just like CSS.

This is totally wrong, and a very dangerous way of handling date/time issues. If you set a wake-up alarm for 7am, you want that to go off at 7am in your local timezone, not 7am in whatever timezone you set the alarm in (which is what an ”absolute” time stamp would store).

There are lots of examples like this. Some time events you want to happen at absolute time points (in which case time zones are only for display purposes), but very often your events need to be ”time-zone aware”. There is no universal rule, and thinking that there is will lead to all sorts of trouble.

It's not wrong. What you're describing is not a timestamp.

A timestamp is a point in time, and is the same everywhere (excluding relativistic effects).

What you describe is definitely a valid use case (and having developed software that programs hardware that is controlled by a calendar, I have painful experience in this). However, it's not a timestamp. I'd call it time-of-day or wallclock. Some systems like SQL refers to it as simply "date" and "time". Whatever you prefer to call it, it's not a timestamp.

Could you add something saying explicitly what a timestamp _is_ under your terminology? Is it an integer offset from the UNIX era start?

It's an abstract concept. It's nothing more than a given point in time.

How you represent it doesn't change the definition. It could be stored as the number of seconds since some arbitrary point in time, such as Unix timestamp, or a Julian timestamp.

Or, it could be a given time and date combination with some fixed point of reference, such as UTC. I'm sure we all have favourite ways of representing timestamps.

Ok, one thing — perhaps not the most important — is that “timestamp” is a very unfortunate terminology for the abstract concept you describe. The word timestamp very much suggests that it’s referring to an explicit representation of some sort. “timepoint” would be much better for what you’re talking about. Not a criticism of you of course! I mostly write python at work so I rarely am directly exposed to the integer offset values, but I know many people use the word “timestamp” to refer to that integer, as opposed to a formatted string. Which also seems like unfortunate terminology, since what is a stamp if not formatted?

You are assuming that timezones don't change ever in relation to UTC. This is wrong. Timezones change all the time.

When I set an alarm for any time in CEST in 2022 and convert this to UTC before saving it, it will very likely ring at the wrong time, simply because CEST will probably not exist by then and be replaced by CET due to the EU getting rid of DST.

But an alarm is not supposed to use timestamps. An alarm is set for a certain time in a certain location. In otherwords, a wallclock time. Not a timestamp.

No, timezone information can be critical and assuming you can always strip it is just wrong.

You might not have encountered such scenarios but they are very much out there.

> No, timezone information can be critical and assuming you can always strip it is just wrong.

Expressing time based on the standard reference timezones (i.e., UTC) is not stripping the time zone away.

It is. Timezones change all the time in relation to UTC. If you set a date in the future and think converting it to UTC doesn't lose information, you will be surprised when you get bitten by it.

Example: The EU will most likely get rid of DST around 2022. Any time you set beforehand in CEST or CET will be an hour off, depending on which the EU will get rid of.aybe the EU doesn't get rid of DST and keeps it, you don't know. So unless you have a time machine, you cannot convert the time to UTC.

> A timestamp is a point in time, whatever the time is in Paris or Tokyo. It is an abstract value and it is way better this way.

> Timezone is extra styling information, just like CSS.

This is an incredibly reductive view of time data and the possible applications that use it.

Not all time data is timestamps, and UTC timestamps strip out information that is not "styling".

> Epoch doesn't carry timezone information.

Dates should not be encoded with time zone info anyway, as timezones is context-dependent. Dates should be encoded in UTC and then let clients interpret them according to their context.

What do you do when timezones change? This happens all the time around the world.

epoch is INHERENTLY timestamped it's seconds since January 1, 1970 (midnight UTC/GMT). it'd be useless if it was just "you know midnight _somewhere_ on Jan 1 1970... pfft it was a long time ago. who cares"

When you go one hour back for daylight savings, you can't tell with just epoch if it's the first or second time you're at that time. With timezones you can, since it switches between PST and PDT.

This is fundamentally incorrect. Because UTC doesn't change, the two "identical" times are different UTC values.

What happened when you set an alarm for 2022 in CEST? The EU will very likely get rid of DST by then.

You alarm will be an hour off when you convert to UTC beforehand.

I don't know that much about epoch, but isn't the point of it to be completely independent of stuff like timezones or daylight savings? Doesn't it track every second since 1970 no matter if meanwhile time jumped back or forward in some countries?

UTC has leap seconds, but otherwise this is correct.

1:30PST and 1:30PDT bijectively map to distinct UTC timestamps.

1. It is lower fidelity (seconds vs milliseconds). 2. It's also not a type. How do you distinguish epoch from number?

> It's also not a type. How do you distinguish epoch from number?

I dunno, how do you distinguish "April" (the month) vs "April" (someone's first name) or 18 (kg) vs 18 ($) vs 18 (-th of the month) vs 18 (page number)?

> It is lower fidelity (seconds vs milliseconds).

This isn't a problem if you have a conforming implementation (2^52 milliseconds is over 100'000 years), but as nitrogen pointed out, you do apparently have to worry about that.

What the original poster means is that if I go JSON.parse(...) then how does that know to give me an object with a Date type instead of a Number? Answer: It can't.

This is a frequent gotcha with Typescript, where even if your type is declared with a Date field, Javascript won't care when it deserializes it, as that type information is all erased and not available at runtime.

(Also, Number in JS being floating point and all, it lacks the integer precision for high resolution timestamps - if you start serialising 64 bit timestamps and expect a JS-style runtime to do good things with them it doesn't end well.)

> how does that know to give me an object with a Date type instead of a Number

Ah, thanks, that makes sense; I'd forgotten that Javascript had a built-in Date type. (Strictly speaking, then, you ought to be able to write something like `{"time":new Date(...)}`, but that obviously doesn't work in practice.)

Since Typescript is mentioned, might as well mention the awesome io-ts[1] library. It gives you both runtime validation and static type safety with very simple syntax.

[1]: https://github.com/gcanti/io-ts

> I dunno, how do you distinguish "April" (the month) vs "April" (someone's first name) or 18 (kg) vs 18 ($) vs 18 (-th of the month) vs 18 (page number)?

Types! Extensible types. Like I said above, Transit is a good solution to this. With a fixed set of types, arbitrary data will always have ambiguity.

1. You could use a float. 2. Probably in the documentation of whatever it is that's using it

Floats are ugly because the distance between any two successive numbers are not the same. This makes them inappropriate for discretized time and anything accounting-related (money).

Epoch floats and doubles are not good for timestamps, as the further we get from 1970 the less precise they become.

Current precision with a 32-bit float (JSON/JavaScript are 64-bit usually, though in non-JS it's common to use Bigdecimal in slight non-compliance) is much worse than one second.

> in the documentation of whatever it is that's using it

That's the point, timestamps should be self-describing. If "look up the structure in documentation" suffices we might as well just use protobufs.

1. YUK 2. ISO 8601 is a better format for this.

That's a timestamp, not a date.

Maybe OP meant timestamp, but that's not what they wrote.