139

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
desertnaut
  • 57,590
  • 26
  • 140
  • 166
Patrick Savalle
  • 4,068
  • 3
  • 22
  • 24

5 Answers5

242

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.

Kriil
  • 560
  • 7
  • 15
Pascal
  • 2,575
  • 1
  • 8
  • 11
  • 2
    specifying the `pattern` is useful for documentation UI (like Swagger) end-users because the format `date` is not explicitly displayed (contrary to `date-time`). – Cethy Oct 24 '18 at 14:06
  • 1
    Is there a way to mention only time? – Sridhar Oct 26 '18 at 08:05
  • 3
    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 – Mrinmoy Apr 16 '19 at 04:46
  • How is it a good example when there is no code mentioned here? – Utkarsh Dubey Sep 28 '22 at 06:44
18

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"
Filipe Bezerra de Sousa
  • 2,874
  • 1
  • 17
  • 17
  • How can we give DateTime both here? – PAA Sep 08 '21 at 05:28
  • 4
    Why are you wrapping each field in ()? And why the second group is ignore? Thanks – Pastello Mar 29 '22 at 07:36
  • 5
    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. – Abel Jun 16 '22 at 12:23
  • 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. – Kriil Apr 27 '23 at 14:54
10

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.

Community
  • 1
  • 1
Kriil
  • 560
  • 7
  • 15
  • 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 – Pankaj Upadhyay Aug 04 '19 at 11:48
  • 5
    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. – Kriil Aug 04 '19 at 17:02
5

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.

Benjamin Buch
  • 4,752
  • 7
  • 28
  • 51
sendon1982
  • 9,982
  • 61
  • 44
-2

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"
amitsriv99
  • 113
  • 1
  • 4