From 5dc5e42058ae7e0419fbae2f5c378db8a69cbbd5 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 6 May 2015 16:40:21 -0700 Subject: [PATCH] versions/2.0: Add a 'duration' format 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], 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 --- versions/2.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/2.0.md b/versions/2.0.md index a3005b1e7d..dd20e8a443 100755 --- a/versions/2.0.md +++ b/versions/2.0.md @@ -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