[docs] Clarify that DateTimeKnownEncoding.unixTimestamp is seconds (not milliseconds)

[mikeharder]

I think the documentation for DateTimeKnownEncoding.unixTimestamp at https://github.com/microsoft/typespec/blob/main/docs/libraries/http/encoding.md#utcdatetime-and-offsetdatetime can be improved:

1. Specify that the timestamp is the number of seconds since the epoch (not milliseconds like JavaScript Date).

2. Update the example payload to use timestamp in seconds rather than milliseconds:

< "createdAtUnix": 1665559250520
> "createdAtUnix": 1665559250

Related:

• [Bug]Generator using fromUnixTimeSeconds for unixTimestamp with int64 Azure/autorest.csharp#4189 (comment)
• Feature/datamap tsp Azure/azure-rest-api-specs#26702 (comment)

[mikeharder]

From @johanste:

@bterlson, this was intended as seconds, not milliseconds, right?

[bterlson]

Unix time as far as I understand it is properly understood to be seconds since epoch and stored in a 32 bit integer.

[bterlson]

And yeah, the docs should be updated. We called the scalar type unixTimestamp32 to avoid this confusion, but unfortunately DateTimeKnownEncoding does not make things as clear.

[mikeharder]

@bterlson: For the spec in question:

Azure/autorest.csharp#4189 (comment)
Azure/azure-rest-api-specs#26702 (comment)

The service does use milliseconds since epoch. How should this be represented in TypeSpec?

[bterlson]

I think we have to add a known encoding for that? @timotheeguerin may know more.

Also note that you would probably encode it as a safeint instead of an int64 (53 bits is good enough for 285 ka with ms granularity).

[timotheeguerin]

yeah we'd have to define a new encoding as just saying the same encoding on an int64 target would still be seconds but with an int64 type. (basically unixtimestamp64)

If we want to have a type that allows second we should have a unixTimestampWithMilli or whatever else is the type usually called.

And yeah lets update the docs to be clear that this encoding means encoded as an integer of seconds

[timotheeguerin]

This website seems to be showing a good set of examples how unixtimestamp with millisseconds is represented in different language
https://currentmillis.com/

Usually seems to either have no way to do it or just suffixed with milliseconds

[bterlson]

I am not sure I like changing the semantics of the encoded value based on the data type you store the ecoded value in? Do we have other cases of that? Also I would prefer to see safeint in virtually all instances of this (int64 has interoperability issues in JSON), and it's less clear that safeint implies ms granularity.

[timotheeguerin]

I mean

@encode("unixTimestamp", int32)
scalar unixTimestamp32 extends utcDateTime;

@encode("unixTimestamp", int64)
scalar unixTimestamp64 extends utcDateTime;  // This is seconds it is consitent we are just saying that the data type used is int64 not int32

// Now here we define a different encoding
@encode("unixTimestampMilliseconds", int64)
scalar unixTimestampMilliseconds64 extends utcDateTime;

[bterlson]

ah ok sorry I misread your comment. Yes, I think that's the general shape of things, though we could bikeshed name some (and also probably want to add a scalar for the safeint variant).

[markcowl]

est: 1

[mikeharder]

@timotheeguerin: Can you please update https://github.com/microsoft/typespec/blob/main/docs/libraries/http/encoding.md#utcdatetime-and-offsetdatetime as well? As stated in the OP, the example is very misleading (shows a value of milliseconds since epoch).