Openapi-specification: Date format too strict

[tadhgpearson]

Swagger dateTime format requires use of the RFC date-time format which is a subset of the ISO Datetime format that does not leave minutes and seconds as optional.

I'm working on APIs for the Travel Industry, where things are never scheduled to the second. Most flights and trains operate to minutes, most car rentals work to the nearest hour. I don't want to compromise my APIs to deliver meaningless minutes and seconds values just to please Swagger.

See https://groups.google.com/forum/#!topic/swagger-swaggersocket/S3ehhOPqink

[webron]

@tadhgpearson - thanks for opening the ticket.

Just want to add that the definition of date-time is taken from the JSON Schema Validation spec as described here - http://json-schema.org/latest/json-schema-validation.html#anchor108. Changing that behavior means deviating from JSON Schema, which is definitely an option, but it's important to note the source of it.

[tadhgpearson]

Thanks Ron.

The main issue with this for us is date parsing in the client libraries for Swagger Generator.
From the little I've seen, the date parsing on these clients can be quite hairy sometimes. When I have a chance to look at them in more detail, I'll try to open some issues there, hopefully accompanied with pull requests to fix them ;)

[m-radzikowski]

I don't see any option to globally change date format presented by Swagger too. For example we are always serializing dates always full offset for timezone, for example "+00:00" or "+02:00". It's still ISO-8601 compliant and we would like to show this format in examples, not with "Z".

[tadhgpearson]

@m-radzikowski - Indeed, this is something else that we find. No-one wants times in UTC. Local time + timezone is king.

Neither of these are supported by Swagger formats now, so we just say _type: string_ and try our best to document the format in the description :/

[tadhgpearson]

BTW - there's nothing preventing the definition of another format. For example, _format: iso-date-time_ could define any ISO 8601 date time as valid.

JSON schema does let you define your own formats - if the tool doesn't understand a given format it should flag all values as 'valid', so all you need is that the tools you need to support your formats
http://json-schema.org/latest/json-schema-validation.html#anchor105

Of course, having it in the spec would speed up adoption ;)

[webron]

Tackling PR: #741

[fehguy]

We support date, date-time and you can invent your own formats. My suggestion is that we stick with those. @webron can you please see if we need more specifics around this?

[tadhgpearson]

@fehguy - I guess what would be useful is most languages have a date/time library that supports ISO 8601 dates. It would be useful to have a format, like iso-date that would cause Swagger tools to invoke the language's ISO date parse / format methods.

[webron]

We've discussed in the past the option to have as part of the OAI, a format registry with a formal process of adding and registering new formats that would be commonly addressed by various tools.

Keeping it inside and as part of the spec is ill-advised as it will make constant changes to the spec, bumping minor versions needlessly.

As such, I'd suggest keeping the minimal list we have now, and keep exploring the registry idea in the future. More information can be found in #845. In fact, I'll close this ticket as we now have a reference between the two.