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.

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.