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

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

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

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 - 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 :/

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 ;)

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.