What is the correct way to declare a date in an OpenAPI / Swagger-file?

Question

What is the correct way to declare a date in a swagger-file object? I would think it is:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date

But I see a lot of declarations like these:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date
    pattern: "YYYY-MM-DD"
    minLength: 0
    maxLength: 10

Thanks.

Answer 1

The OpenAPI Specification says that you must use:

type: string format: date # or date-time

The patterns supported are defined in RFC 3339, section 5.6 (effectively ISO 8601) and examples are provided in section 5.8. So for date values should look like "2018-03-20" and for date-time, "2018-03-20T09:12:28Z". As such, when using date or date-time, the pattern is unnecessary and in fact, should be omitted.

If you need to support dates/times formatted in a way that differs to RFC 3339, you are not allowed to specify your parameter as format: date or format: date-time. Instead, you should specify format: string with an appropriate pattern.

Finally, note that a pattern of "YYYY-MM-DD" is invalid according to the specification: pattern must be a regular expression, not a placeholder or format string.

If you are violating any of the above rules to work around bugs in tools that generate UIs from OpenAPI specifications, you should strongly consider raising these bugs with that tool, rather than generating an invalid OpenAPI spec to work around this.