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

Pure

Answer 1

The OpenAPI Specification says that you must use:

type: string
format: date # or date-time

The internet date/time standard used by OpenAPI is 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 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 type: string with an appropriate pattern and remove format.

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.

Waldon

specifying the pattern is useful for documentation UI (like Swagger) end-users because the format date is not explicitly displayed (contrary to date-time). – Secretion

Is there a way to mention only time? – Blodget

What if if you API dont accept the dates in the format supoorted/suggested by OpenAPI. Will you change your API or the Spec ?. I will change the spec and use Pattern instead of changing my API signature. Therefore people use pattern, or simply provide it in a description – Mckenziemckeon

How is it a good example when there is no code mentioned here? – Lactation

This seems to be specific to OpenAPi v 3.0.3 (github.com/OAI/OpenAPI-Specification/blob/master/versions/…) and removed in v 3.1.0 (github.com/OAI/OpenAPI-Specification/blob/main/versions/…) – Sykes

OpenAPI 3.1.0 references JSON Schema Validation vocabulary instead, which seems effectively the same regarding date and date-time – Apophasis

Answer 2

A correct example of declaring date in an Open API swagger file:

    properties:
      releaseDate:
        type: date
        pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
        example: "2019-05-17"

Henig

How can we give DateTime both here? – Venterea

Why are you wrapping each field in ()? And why the second group is ignore? Thanks – Turenne

Use format: date and don't use pattern, much easier to read. If you do want to use a regex for a different date format, do not use type: date, but type: string instead. – Garcon

The spec indicates that pattern should only be used when the date does not follow the standard as defined in RFC3339. In which case the type should be string and not date. – Smoothtongued

Also, pattern in OAS is a string (quoted or unquoted). Neither JSON nor YAML support slash-limited RegExp literals natively. – Apophasis

Answer 3

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.

Smoothtongued

one should strict with the format defined for date time, that can be localised to client format while displaying but for API one should use standard Internet Date/Time Format – Experimentation

The format defined for the OpenAPI spec IS the standard internet date/time format. However, you might find web services that you didn't write or don't have access to that don't follow the standard. In those cases, you still need to be able to define the date/time format using OpenAPI. Using pattern solves the issue. – Smoothtongued

Answer 4

An example of OpenAPI 3 is based on document here:

https://swagger.io/docs/specification/data-models/data-types/

An optional format modifier serves as a hint at the contents and format of the string. OpenAPI defines the following built-in string formats:

date – full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

date-time – the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

BookingNoteRequest:
  type: object
  properties:
    note:
      type: string
    postedDate:
      type: string
      format: date
      example: '2022-07-01'
    postedTime:
      type: string
      format: date-time
      example: '2017-07-21T17:32:28Z'

If the date or date-time format does not follow the standard as defined by RFC 3339, then the format field should be removed and the pattern field added with a regular expression defining the format.

Showalter

Answer 5

For Swagger 2.0

 /room-availability:
    get:
      tags:
      - "realtime price & availability"
      summary: "Check realtime price & availability"
      description: "Check realtime price & availability"
      operationId: "getRealtimeQuote"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "checkInDate"
        description: "Check-in Date in DD-MM-YYYY format"
        type: "string"
        pattern: "^(3[01]|[12][0-9]|0[1-9])-(1[0-2]|0[1-9])-[0-9]{4}$"
      - in: "query"
        name: "numOfGuests"
        description: "Number of guests"
        type: "integer"
        format: "int16"
      - in: "query"
        name: "numOfNightsStay"
        description: "number of nights stay"
        type: "integer"
        format: "int16"
      - in: "query"
        name: "roomType"
        description: "Room type"
        type: "string"
        enum:
        - "King Size"
        - "Queen Size"
        - "Standard Room"
        - "Executive Suite"
      - in: "query"
        name: "hotelId"
        description: "Hotel Id"
        type: "string"

Which