What is a good format for Duration in JSON?

Question

I realise that JSON has no real date format and that using ISO 8601 is a good bet given that's what JavaScript uses. What about a duration? JavaScript has no built in format.

1. I came across ISO 8601 Durations e.g. P3Y6M4DT12H30M5S which I haven't seen used much in the wild. It also looks very verbose and difficult to read. As far as I can see it also does not support milliseconds if you needed that.
2. I'm using C# whose TimeSpan type outputs 1.02:03:04.0050000 for 1 day, 2 hours, 3 minutes, 4 seconds and 5 milliseconds.
3. I could use the number of seconds or milliseconds as an integer. This is completely machine readable only and it's not obvious if you are using seconds or milliseconds without labelling the value as such.

I've hardly ever seen the first format in the wild. The second seems more intuitive to me but I'm worried that it's not as well known outside of .NET. The third format is probably the most cross platform friendly but totally not human readable.

Sausage

Note that duration and time are not exactly the same. When you are traversing across time zones, duration does not change but time does. This can lead to complications when representing time in a way meant to be consumed outside of your program using only a duration. – Threadbare

Yes, I was unsure of the wording. I'm really talking about Duration. – Sausage

As you say, JSON doesn't have direct support for this, so really it's up to the producer and consumer of the JSON to agree on something that makes sense for that particular scenario. – Yippie

To answer your millisecond question, the last unit in 8601 supports a fraction, per the documentation you linked. So a millisecond seems possible. – Threadbare

As you found out, there is no "credible and/or official sources". JSON misses so many things... Anyway, I also use .NET so I choose TimeSpan.Ticks which is an Int64. JSON supports any type of integer, but Javascript only up to MAX_SAFE_INTEGER (9007199254740991). So, if Javascript interop is needed, I'll only be able to represent up to 10424.23:58:45.4740991 (~10k days). – Littman

Answer 1

Basically, duration is a number of milliseconds or ticks (if you need higher precision).

1 tick is 100 nanoseconds. There are 10,000 ticks in a millisecond.

ISO 8601: the existing standard

The best way is to use common standard that you mentioned ISO 8601. It's human and machine readable.

What is easier to read and change for you?

• 1036800000 ms
• P12D

You can use ISO 8601 duration like P1Y2M10DT2H30M in different ways:

• Handle by moment.js in JavaScript
• Pass in JSON format as a string value
• Handle by NodaTime in C#
• Store in DB

Keep in mind that ISO 8601 also resolves the issue when switching from or to Daylight saving time.

PT36H is not the same as P1DT12H.

Schema.org

There are different schemas for structured data on the Internet on schema.org. Number of them are using Duration which should be represented by ISO 8601 duration format.

Accusal

Answer 2

I think the usage of ISO 8601 Durations is the best option. It also supports milliseconds, if you use decimal fraction. For example: "PT0.0001S" represents 1 ms.

Wikipedia: The smallest value used may also have a decimal fraction,[38] as in "P0.5Y" to indicate half a year. This decimal fraction may be specified with either a comma or a full stop, as in "P0,5Y" or "P0.5Y".

But the problem is, that JSON brings a format for duration which only supports RFC 3339. This does not support milliseconds (no fraction):

• https://spec.openapis.org/registry/format/
• https://datatracker.ietf.org/doc/html/rfc3339#page-12

Lylalyle

Answer 3

I think that seconds (or for shorter duration items that require that level of accuracy, milliseconds) is the expected unit.

Ppm