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
    exampl         


        

Answer 1

pattern should be a regular expression. This is stated in the OpenAPI Specification.

pattern (This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect)

This is because OpenAPI objects are based off the JSON Schema specification.

OpenAPI 2.0: This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.

OpenAPI 3.0: This object is an extended subset of the JSON Schema Specification Wright Draft 00.

If a web service exposes a date or a date-time that doesn't conform to the Internet Date/Time Format described in RFC3339, then date and date-time are not valid values for the format field. The property must be defined as having a type equal to string without using format. Instead, pattern can be used to give a regular expression that defines the date or date-time pattern. This allows a client tool to automatically parse the date or date-time.

I also recommend putting the format in the description field so human consumers can read it more easily.