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

Answer 1

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.

Answer 2

In OpenAPI, the date-time format is used to define a string that represents a date and time according to the ISO 8601 standard. This format includes a full date and time in UTC, typically expressed as follows

YYYY-MM-DDThh:mm:ssZ

Here’s a breakdown:

• YYYY = Four-digit year

• MM = Two-digit month (01-12)

• DD = Two-digit day of the month (01-31)

• T = A separator between the date and time components

• hh = Two-digit hour (00-23)

• mm = Two-digit minutes (00-59)

• ss = Two-digit seconds (00-59)

• Z = UTC indicator ("Z" stands for Zulu time, another name for UTC)

Regex for this: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$

CODE

import (
    "fmt"
    "regexp"
)

func main() {
    // ISO 8601 `date-time` regex pattern
    iso8601Regex := `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$`

    // Compile the regex
    r, _ := regexp.Compile(iso8601Regex)

    // Example date-time strings
    validDateTime := "2024-08-20T14:30:00Z"
    invalidDateTime := "2024-08-20 14:30:00"

    // Validate the strings
    fmt.Printf("Is '%s' valid? %t\n", validDateTime, r.MatchString(validDateTime))
    fmt.Printf("Is '%s' valid? %t\n", invalidDateTime, r.MatchString(invalidDateTime))
}

Answer 3

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"

Answer 4

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.

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"

Answer 6

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.