version/3.0: Add a 'duration' format

[wking]

Spun off from #356 to avoid PRs which don't attract comments ;).

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 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, you can instantiate Dates from those millisecond
offsets, and durations are in milliseconds by default.

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

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, but it
doesn't appear to parse that format.

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

Go parses durations from its own format.

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

[ralfhandl]

Would be useful for OData and its Duration primitive type which uses xsd:dayTimeDuration format

[webron]

Tackling PR: #741

[webron]

Will be tackled in #845 instead.

[webron]

Closing as all tickets will be tackled there.

[NathanHazout]

Reviving an old thread here, wanting to tackle a bunch of issues within the same ticket is fine, but reading through that long ticket gave me no clue at to what the conclusion was, or how to use ISO 8601 durations in my OpenAPI document...

[MikeRalphson]

Sorry, in a bit of a rush, but basically:

• format is an open-ended keyword, you can use any value
• duration was added to JSON Schema as a format value to indicate ISO-8601 durations in Draft 2019-09. OAS will not define conflicting behaviour

[wking]

duration was added to JSON Schema as a format value to indicate ISO-8601 durations in Draft 2019-09.

Wonderful :) Even better than something OpenAPI-specific.

[NathanHazout]

Thanks, does OpenAPI already support JSONSchema's Draft 2019-09? If so from what version?

Meaning can I expect implementations of OAS to support duration, assuming they support the latest release of OAS?

[MikeRalphson]

OAS 3.1 (in RC stage) supports JSON Schema draft 2019-09, 3.1 final should hopefully support JSON Schema draft 2020-XX (which is as-yet unpublished).

There is a wrinkle, in that JSON Schema 2019+ defines format as an annotation, not a validation keyword, so by default compliant tools will not enforce ISO-8601 duration patterns against a format: duration annotation. Like JSON Schema, the OAS leaves the choice of whether to do a best-effort validation of format up to tooling.

You can use format: duration now in OAS 2.0/3.0.x (just without tooling support).

[handrews]

@nasht00 note that the "not a validation assertion by default" is due to format never having been implemented consistently for validation. The date and time formats tend to be well-supported, but others tend to be partially supported (e.g. validation of email being done as just checking for an @ sign) or use inconsistent definitions (e.g. validation of regex being done according to whatever regex syntax is supported by the implementation language, even if that doesn't quite align with the ECMA standard cited in the spec).

The expectation is that the new modular extension vocabulary support will result in well-defined validation keywords being created that don't staple completely unrelated concepts together. A date and time vocabulary with well-defined validation keywords would be very easy to add, as those concepts have very clear specifications from IETF and/or ISO.