Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

version/3.0: Add a 'duration' format #359

Closed
wking opened this issue May 7, 2015 · 10 comments
Closed

version/3.0: Add a 'duration' format #359

wking opened this issue May 7, 2015 · 10 comments

Comments

@wking
Copy link

wking commented May 7, 2015

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.

wking added a commit to azurestandard/api-spec that referenced this issue May 7, 2015
We only create stops at verification time, but folks will want to have
estimated delivery times while they're shopping for their order.
David confirmed that a single model should store the usual offset
between the start of delivery and a given drop on a route, so we need
to expose that data publically.  This commit specifies that API and
adjusts the stop description to explain that it's only useful for
verified trips.

The duration format specifies ISO 8601 durations [1,2].  I've proposed
it for inclusion in future versions of Swagger [3], but until that's
accepted we're using it as a custom format [4].

[1]: https://tools.ietf.org/html/rfc3339#page-13
[2]: http://en.wikipedia.org/wiki/ISO_8601#Durations
[3]: OAI/OpenAPI-Specification#359
[4]: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#data-types
     Swagger uses several known formats to more finely define the data
     type being used. However, the format property is an open
     string-valued property, and can have any value to support
     documentation needs. Formats such as "email", "uuid", etc., can
     be used even though they are not defined by this specification.
@ralfhandl
Copy link
Contributor

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

@webron
Copy link
Member

webron commented Jul 21, 2016

Tackling PR: #741

@webron
Copy link
Member

webron commented Feb 22, 2017

Will be tackled in #845 instead.

@webron
Copy link
Member

webron commented Mar 2, 2017

Closing as all tickets will be tackled there.

@NathanHazout
Copy link

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
Copy link
Member

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
Copy link
Author

wking commented Oct 8, 2020

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
Copy link

NathanHazout commented Oct 8, 2020

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
Copy link
Member

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
Copy link
Member

handrews commented Oct 8, 2020

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants