In OpenAPI 3.0, should I specify maxLength for a string with a specified format?

user_17209701 0
Viewed 728

I have some string parameters with specified format in my OpenAPI documentation.

email:
  type: string
  format: email
hostname:
  type: string
  format: hostname
path:
  type: string
  format: uri

I want to define maxLength to protect from harmful queries. Do I have to do it or does format already define the maximum length?

openapi
1 Answers

For some of the formats the length of its value is defined. You can refer https://github.com/OAI/OpenAPI-Specification/issues/607#issue-142290879 to get the RFC definition for these formats. Apart from those if you think you need to have your predefined max/min length for the string value you can add them or you can use pattern keyword as well if you want to introduce any custom formats in your API definition. Using format has its own advantage and disadvantages.

Advantage

  1. You can keep the API definition clean with few lines
  2. You don't have to worry about the length if you want to follow a generally accepted lengths for your payload parameters.

Disadvantage

  1. You have to stick to a predefined format
  2. If you are not aware of the format details then your requests/responses might get failed.
user_80326050
Related