OpenAPI tips - Data types and formats


Hi! These blog posts have been popular, so we’ve built an entire OpenAPI Reference Guide to answer any questions you have.
It includes detailed information on data types.
Happy Spec Writing!
The problem
The OpenAPI spec is best known for descriptions of RESTful APIs, but it’s designed to be capable of describing any HTTP API whether that be REST or something more akin to RPC based calls.
That leads to the spec having a lot of flexibility baked-in: there’s a lot of ways to achieve the exact same result that are equally valid in the eyes of the spec. Because of this, the OpenAPI documentation is very ambiguous when it comes to how you should define your API.
That’s why we’re taking the time to eliminate some of the most common ambiguities that you’ll encounter when you build your OpenAPI spec. In this case we’ll be taking a look at how to effectively use data types in your OpenAPI 3.0.X spec.
Note: We will cover the differences introduced by 3.1 in a future post.
Recommended practices
The OpenAPI Spec gives you plenty of options for describing your types, but also a lot of options to describe them loosely. Loose is fine if your goal is to have a spec that is valid, but if you are using your OpenAPI document to generate: code, documentation or other artifacts, loose will get you into trouble.
Describe your types as accurately as possible; you will not only improve the documentation of your API reducing ambiguity for end-users), but will give as much information as possible to any tools you might be using to generate code, documentation or other artifacts from your OpenAPI document. Concretely, we recommend that you:
- Describe your types as explicitly as possible by using the OpenAPI defined formats.
- Use additional validation attributes as much as possible: mark properties as required, set readOnly/writeOnly, and indicate when fields that are nullable.
Below, we will step through the different types available in OpenAPI and explain how to use formats, patterns and additional attributes to give you a spec that is descriptive and explicit.
The data types
In addition to an object type, for custom type definitions, the OpenAPI Specification supports most of the “primitive” types and objects you would expect to describe what your API is capable of sending and receiving:
For each of these primitive types, there is a set of commonly-used formats (i.e. date format for string) which you can designate to enforce additional constraints on the values of a schema or field. There is also the option of associating a nullable attribute. These options lead to a number of different possibilities for describing your data.
The OpenAPI Spec also includes the ability to describe more complex relationships between types using the oneOf/anyOf/allOf attributes and providing the ability to describe enums but we will leave the discussion of them to a future blog post.
For now, let’s explore the various types and options available for describing your types.
string
Of the primitive types (ignoring the object type) , the string type is the most flexible type available. In addition to being able to be used to represent other types (such as “true”
, “100”
, “{\\“some\\”: \\”object\\”}”
), it supports a number of formats that overlay constraints to the type of data represented. This is useful for mapping to types in various languages if you are using the OpenAPI spec for code generation.
Formats
The string type via the OpenAPI Specification officially supports the below formats:
String Data Types and Formats
Type | Format | Explanation | Example |
---|---|---|---|
string | date | An RFC3339 formatted date string | "2022-01-30" |
string | date-time | An RFC3339 formatted date-time string | "2019-10-12T07:20:50.52Z" |
string | password | Provides a hint that the string may contain sensitive information. | "mySecretWord1234" |
string | byte | Base-64 encoded data. | "U3BlYWtlYXN5IG1ha2VzIHdvcmtpbmcgd2l0aCBBUElzIGZ1biE=" |
string | binary | Binary data, used to represent the contents of a file. | "01010101110001" |
The format attribute can also be used to describe a number of other formats the string might represent but outside the official list above, those formats might not be supported by tooling that works with the OpenAPI Spec, meaning that they would be provided more as hints to end-users of the API:
- uuid
- uri
- hostname
- ipv4 & ipv6
- and others
Below are some examples of describing various string types:
Patterns
The string type also has an associated pattern attribute that can be provided to define a regular expression that should be matched by any string represented by that type. The format of the regular expression is based on Javascript and therefore could describe regular expressions that might not be supported by various tools or target languages, so make sure to check the compatibility with your intended targets.
Example of a string defined with a regex pattern:
number/integer
The number/integer types allow the description of various number formats through a combination of the type and format attributes, along with a number of attributes for validating the data, the spec should cover most use cases.
Available formats are:
Numeric Data Types and Formats
Type | Format | Explanation | Example |
---|---|---|---|
number | Any number integer/float at any precision. | 10 or 1.9 or 9223372036854775807 | |
number | float | 32-bit floating point number. | 1.9 |
number | double | 64-bit floating point number. | 1.7976931348623157 |
integer | Any integer number. | 2147483647 or 9223372036854775807 | |
integer | int32 | 32-bit integer. | 2147483647 |
integer | int64 | 64-bit integer. | 9223372036854775807 |
Below are some examples of defining number/integer types:
Various tools may treat a number/integer without a format attribute as a type capable of holding the closest representation of that number in the target language. For example, a number might be represented by a double, and an integer by an int64. Therefore, it’s recommended that you be explicit with the format of your number type and always populate the format attribute.
The number type also has some optional attributes for additional validation:
- minimum: The minimum inclusive number the value should contain.
- maximum: The maximum inclusive number the value should contain.
- exclusiveMinimum: Make the minimum number exclusive.
- exclusiveMaximum: Make the maximum number exclusive.
- multipleOf: Specify the number/integer is a multiple of the provided value.
Some examples are below:
boolean
The boolean type is simple; it represents either true or false. Be aware that it doesn’t support other truthy/falsy values like: 1 or 0, an empty string “” or null. It has no additional attributes to control its format or validation.
array
The array type provides a way of defining a list of other types through providing an items attribute that represents the schema of the type contained in the array.
The array type will support any schema that describes any other type in its items attribute including types using oneOf/anyOf/allOf attributes. The array type also has some optional attributes for additional validation:
- minItems: The minimum number of items the array must contain.
- maxItems: The maximum number of items the array must contain.
- uniqueItems: The array must contain only unique items.
object
The object type allows simple and complex objects, dictionaries, and free-form objects, along with a number of attributes to control validation.
Fully typed object
Fully typed objects can be described by providing a properties attribute that lists each property of the object and its associated type.
Objects with properties have access to some additional attributes that allow the objects to be validated in various ways:
- required: A list of properties that are required. Specified at the object level.
- readOnly: A property that is only available in a response.
- writeOnly: A property that is only available in a request.
Using object for dictionaries
The object type can also be used to describe dictionaries/maps/etc that use strings for keys and support any value type that can be described by the OpenAPI Spec.
You can also describe dictionaries that will contain certain keys
When using the additionalProperties attribute you can also specify additional attributes to validate the number of properties in the object:
- minProperties: The minimum number of properties allowed in the object.
- maxProperties: The maximum number of properties allowed in the object.
For example:
Free-form objects
The object type can also be used to describe any arbitrary key/value pair (where the keys are still required to be strings).
null
OpenAPI 3.0.X doesn’t support a null type but instead allows you to mark a schema as being nullable. This allows that type to either contain a valid value or null.