General principle around time measurement units/formats for various domains (JS, HTTP, HTML, etc)?

[csharrison]

This was brought up in our discussion of a new HTML attribute in the Attribution Reporting API (WICG/attribution-reporting-api#132)

The existing TAG principles (https://w3ctag.github.io/design-principles/#milliseconds) are focused on Javascript APIs. Should those principles be extended to all Web Platform APIs including things like HTML attributes, HTTP headers, etc?

[annevk]

Probably not? At least HTTP uses delta-seconds, HTML uses date and time strings, and both make sense to me given the domain.

I'm not even sure if all APIs ought to use milliseconds. I believe media uses seconds (as floats) pretty consistently (at least in the media element APIs). @padenot might have thoughts here.

[padenot]

I believe media uses seconds (as floats) pretty consistently (at least in the media element APIs). @padenot might have thoughts here.

Various high-level media things use seconds as double (it matters greatly that those are 64-bits double), but for Web Audio API it's a number of sample-frames divided by a sample-rate, it's possible to get an integer from it (which is important). Web Codecs uses integer microseconds, because that's what is expected by authors familiar with codecs. Authors doing advanced audio work are always using integers.

A millisecond is a very long period of time, for media at least, and being able to pick the best unit (or get an integer) and type matters a lot more than always having milliseconds I think, especially in lower level APIs.

[csharrison]

Thanks folks for chiming in, looks like there isn't a ton of value in recommending milliseconds outside of JS APIs (and even then it seems like there is a lot of wiggle room).

Let me pose a slightly different question to @annevk: If we feel that different domains (HTTP / HTML) have different standards that make sense, do we feel this strong enough to write it down as a TAG design principle? Personally I think it would be great if this resource said something like "prefer integer seconds for HTTP and date/time strings for HTML".

[annevk]

Yeah, from other changes it does seem like the document is trying to cover the various domains so that would make sense.

cc @LeaVerou

[LeaVerou]

We definitely want the document to cover the various domains, yes.

Agenda+ing to discuss, since I'm not sure we should even be recommending milliseconds for JS APIs given the existing examples provided here.

[kenchris]

We should definitely remove the text saying to always use milliseconds. It is quite common in DOM APIs though, like setTimeout, setInterval, WebAnimations, Vibrate etc

We also have a few polling APIs using frequency instead (like Generic Sensors).

Telemetry APIs like Performance.now() often use DOMHighResTimestamp which makes sense in that domain.

Maybe we can remove the milliseconds example and instead say to stay consistent with other APIs in the same domain, like the telemetry domain uses DOMHighResTimestamp, etc

[LeaVerou]

We discussed this today in our virtual f2f. It doesn't appear there is one universal guidance here (like what is currently in the spec), APIs across the Web Platform do different things, and often for good reason.

• HTMLMediaElement APIs use seconds
• window.performance uses DOMHighResTimeStamp
• Web Codecs use microseconds as a long
• Web Animations use milliseconds
• ...

Therefore, the guidance needs to be more nuanced than a blanket "use milliseconds and DOMHighResTimeStamp that it is now, and possibly include a list of precedents, so that API Designers can choose what to be compatible with based on their use case.

[LeaVerou]

@kenchris will take a stab at some initial text, and then we can iterate.

[csharrison]

Related: If TAG has advice on when to use HTTP-Date vs. delta seconds (or both, like Retry-After) for header-based APIs that would be appreciated.

[annevk]

I'm pretty certain that if you can use offsets in HTTP, you should. They are much more reliable than timestamps.

[jyasskin]

For the question of HTTP headers, it's worth checking with @mnot.

[mnot]

Using HTTP-Date is problematic for a few reasons:

• Parsing is all over the map, especially around error handling (e.g., see these tests)
• parsing is relatively expensive
• To adjust for clock sync, you need to have a Date header available (which means you need to parse two dates)
• Because of that, potential drift is doubled to two seconds

Delta-seconds are much more straightforward. People sometimes ask for sub second resolution in HTTP headers, but we typically push back on accommodating that in specs, since the RTT for a request can easily make that meaningless at best and a footgun at worst.

People still argue for HTTP-Date or similar in headers (see eg ietf-wg-httpapi/deprecation-header#11 (comment)), mostly for developer ergonomics. IMO that doesn't overcome the deficiencies above, so any help along these lines would be welcome.

I've also toyed with the idea of a Date type in Structured Fields, but the only advantage I see over just using an integer (either delta or epoch) is the ability to display it as a date in things like devtools...

[mnot]

Oh, and fields that have more than one form (like Retry-After) have proven to be problematic; I wouldn't recommend that practice.

[csharrison]

Thanks @mnot for the well-argued and constructive advice, it is really appreciated!

[dret]

agreeing with @mnot in principle, but i think even if there is no need to constrain the syntax in structured fields, it would help a lot to define and make referencable the desired semantics. after all, designers look at structured fields to figure out which data types they can/should use using that spec. having well-defined and referencable definitions for something like DateTime would help a lot (even if it's just an alias for an otherwise unconstrained integer).