OpenAPI String Type and Format

OpenAPI uses the primitive type string to represent simple textual data at either the parameter, request body, response, or schema level. Setting the string format further clarifies the data structure, while limits can be imposed through validation properties maxLength, minLength, enum/const, and pattern.

In the object below, we've defined a property name and set the data type to string in our OpenAPI schema.

When to use string type in OpenAPI

If you have simple textual data, you should use this type. Valid sample values for string type:

When to avoid using a string type

If you have boolean, numeric or complex data (e.g., a list of items or an object with nested properties, each having its own data type), avoid using string type for the following types of values:

Where can a string type be used in OpenAPI?

In an OpenAPI definition, the string type can be used when defining the schema of either a parameter, request body, response, or another schema:

Parameter

Request body

Response

Complex data

OpenAPI String Format

Along with the type information, OpenAPI provides support for setting an open-ended format string in a schema for additional configuration:

Some well-known formats that have wider support across tools include the following:

Additional formats are also part of the JSON schema and are recognized by OpenAPI ecosystem. However, some tools may not fully support them and can instead serve more as “hints” in end-user documentation:

APIMatic offers a few additional formats to enhance the code and documentation generation experience:

OpenAPI String Data Validation

To validate a string-typed data instance, several validation keywords are also available and listed below:

maxLength

This validation keyword helps place restrictions on the “length” of a string data. The value of this validation keyword must be a non-negative integer:

A string instance is valid against this keyword if its length is less than or equal to the value of this keyword.

Valid string instance examples for the above schema:

Invalid string instance examples for the above schema:

minLength

Just like maxLength, this validation keyword also helps place restrictions on the “length” of a string data. The value of this validation keyword must be a non-negative integer:

A string instance is valid against this keyword if its length is greater than or equal to the value of this keyword.

Valid string instance examples for the above schema:

Invalid string instance example for above schema:

pattern

This validation keyword helps ensure that the string value follows particular rules. The value of this validation keyword must be a string value, which is a regular expression, according to the ECMA-262 regular expression dialect:

A string instance is considered valid if the regular expression matches the instance successfully.

Valid string instance examples for the above schema:

Invalid string instance example for above schema:

enum

If you want to ensure that the string data belongs to a specific list of values only, you can do that by using the enum keyword:

The enum, in this case, must contain a unique list of string values since the type has been set to string. A string instance will be considered valid if it is equal to one of the elements in the enum list.

Valid string instance examples for the above schema:

Invalid string instance example for above schema:

const

While enum is a list of possible values, a const helps define a single value the instance must be equal to. In the context of string types, a const must be set to the string value that the instance is expected to be:

Validating the above schema, only the value Red will be considered valid.

Note that this keyword is only available in OpenAPI v3.1 and above.

OpenAPI Nullable Strings

If the string data instance can also be nullable i.e., it can either have a string value or a “null” value, it should be marked accordingly in the OpenAPI definition.

For OpenAPI v3.0, this can be done by setting the property nullable to true:

For OpenAPI v3.1, this can be done by using type as an array containing both types:

Valid string instance examples for the above schema:

Special Considerations for Code Generation and Documentation

When using the string type in code generation and documentation, it can be useful to take care of the following for better output:

Include an example for the string type as that can be beneficial for end-users:

Use the description property to provide additional information about the purpose and expected use of the string:

Make use of well-known formats to specify further the value of the string data instance needs:

To offer clarity to end-users on the type of values that are acceptable and for providing client-side validation support, don’t forget to use validation keywords to put reasonable limits using minLength, maxLength, and pattern:

To limit the values completely, make use of enum:

Conclusion

Use string type in OpenAPI schemas when dealing with simple textual data at either the parameter, request body, response, or schema level. Complement it with an example and a description for better understanding on the user end. Further clarification on structuring the string value can be done by setting the format where possible. Limit the type of values that the string instance can accept by using validation keywords like maxLength, minLength, enum/const, and pattern to increase the overall security and for preventing any errors during API calls.

Looking to improve the quality of your OpenAPI definition? Try APIMatic's  VSCode extension with over 1200 validation and linting rules.