Skip to content

Commit

Permalink
versions/2.0: Add a 'duration' format
Browse files Browse the repository at this point in the history
On IRC today, Tony Tam pointed out that folks currently work around
the lack of durations by using an int64 for millisecond offsets, but
that's not very human readable.  And we care about human-readability
or we'd all be using protobufs instead of JSON, right?  ;).

The support for ISO 8601 durations [1,2] in native JavaScript is
unclear, but both Firefox 31.5 and Chromium 41.0 give:

  > new Date('P3D')
  Invalid Date

So the millisecond approach may be easier to use in JavaScript
applications, where date-times are stored as millisecond offsets from
the epoch [3], you can instantiate Dates from those millisecond
offsets [4], and durations are in milliseconds by default [5].

The Moment.js library supports durations based on millisecond offsets
[6]:

  moment.duration(100);

explicit units:

  moment.duration(2, 'seconds');

and [{day}.]{hour}:{minute}[:{second}[.{fraction}]] strings:

  moment.duration('23:59');
  moment.duration('23:59:59');
  moment.duration('23:59:59.999');
  moment.duration('7.23:59:59.999');

And it renders ISO 8601 durations [7] in ISO 8601 format, but it
doesn't appear to parse that format.

Java parses ISO 8601 durations with an extension to support negative
durations [8].

Go parses durations from its own format [9].

Python has a duration type, but does not parse ISO 8601 durations
[10].

[1]: http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#iso.8601.collected.abnf
[2]: http://en.wikipedia.org/wiki/ISO_8601#Durations
[3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#Description
[4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#Syntax
[5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#Example:_Calculating_elapsed_time
[6]: http://momentjs.com/docs/#/durations/creating/
[7]: http://momentjs.com/docs/#/durations/as-json/
[8]: https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-
[9]: http://golang.org/pkg/time/#ParseDuration
[10]: https://docs.python.org/3/library/datetime.html#timedelta-objects
  • Loading branch information
wking committed May 6, 2015
1 parent 0904fdd commit b63ac1c
Showing 1 changed file with 1 addition and 0 deletions.
1 change: 1 addition & 0 deletions versions/2.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ byte | `string` | `byte` |
boolean | `boolean` | |
date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
duration | `string` | `duration` | As defined by `duration` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#iso.8601.collected.abnf)
password | `string` | `password` | Used to hint UIs the input needs to be obscured.

### Schema
Expand Down

0 comments on commit b63ac1c

Please sign in to comment.