Data Types

The data type of a schema is defined by the type keyword, for example, type: string. OpenAPI defines the following basic types:

string (this includes dates and files)
number
integer
boolean
array
object

These types exist in most programming languages, though they may go by different names. Using these types, you can describe any data structures.

Note that there is no null type; instead, the nullable attribute is used as a modifier of the base type.

Additional type-specific keywords can be used to refine the data type, for example, limit the string length or specify an enum of possible values.

Mixed Types

type takes a single value. type as a list is not valid in OpenAPI (even though it is valid in JSON Schema):

1
# Incorrect
2
type:
3
  - string
4
  - integer

Mixed types can be described using oneOf and anyOf, which specify a list of alternate types:

1
# Correct
2
oneOf:
3
  - type: string
4
  - type: integer

Numbers

OpenAPI has two numeric types, number and integer, where number includes both integer and floating-point numbers. An optional format keyword serves as a hint for the tools to use a specific numeric type:

`type`	`format`	Description
number	–	Any numbers.
number	float	Floating-point numbers.
number	double	Floating-point numbers with double precision.
integer	–	Integer numbers.
integer	int32	Signed 32-bit integers (commonly used integer type).
integer	int64	Signed 64-bit integers (`long` type).

Note that strings containing numbers, such as “17”, are considered strings and not numbers.

Minimum and Maximum

Use the minimum and maximum keywords to specify the range of possible values:

1
type: integer
2
minimum: 1
3
maximum: 20

By default, the minimum and maximum values are included in the range, that is:

1
minimum ≤ value ≤ maximum

To exclude the boundary values, specify exclusiveMinimum: true and exclusiveMaximum: true. For example, you can define a floating-point number range as 0–50 and exclude the 0 value:

1
type: number
2
minimum: 0
3
exclusiveMinimum: true
4
maximum: 50

The word “exclusive” in exclusiveMinimum and exclusiveMaximum means the corresponding boundary is excluded:

Keyword	Description
`exclusiveMinimum: false` or not included	value ≥ `minimum`
`exclusiveMinimum: true`	value > `minimum`
`exclusiveMaximum: false` or not included	value ≤ `maximum`
`exclusiveMaximum: true`	value < `maximum`

Multiples

Use the multipleOf keyword to specify that a number must be the multiple of another number:

1
type: integer
2
multipleOf: 10

The example above matches 10, 20, 30, 0, -10, -20, and so on. multipleOf may be used with floating-point numbers, but in practice this can be unreliable due to the limited precision or floating point math.

1
type: number
2
multipleOf: 2.5

The value of multipleOf must be a positive number, that is, you cannot use multipleOf: -5.

Strings

A string of text is defined as:

1
type: string

String length can be restricted using minLength and maxLength:

1
type: string
2
minLength: 3
3
maxLength: 20

Note that an empty string "" is a valid string unless minLength or pattern is specified.

String Formats

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
password – a hint to UIs to mask the input
byte – base64-encoded characters, for example, U3dhZ2dlciByb2Nrcw==
binary – binary data, used to describe files (see Files below)

However, format is an open value, so you can use any formats, even not those defined by the OpenAPI Specification, such as:

email
uuid
uri
hostname
ipv4
ipv6
and others

Tools can use the format to validate the input or to map the value to a specific type in the chosen programming language. Tools that do not support a specific format may default back to the type alone, as if the format is not specified.

pattern

The pattern keyword lets you define a regular expression template for the string value. Only the values that match this template will be accepted. The regular expression syntax used is from JavaScript (more specifically, ECMA 262). Regular expressions are case-sensitive, that is, [a-z] and [A-Z] are different expressions. For example, the following pattern matches a Social Security Number (SSN) in the 123-45-6789 format:

1
ssn:
2
  type: string
3
  pattern: '^\d{3}-\d{2}-\d{4}$'

Note that the regular expression is enclosed in the ^…$ tokens, where ^ means the beginning of the string, and $ means the end of the string. Without ^…$, pattern works as a partial match, that is, matches any string that contains the specified regular expression. For example, pattern: pet matches pet, petstore and carpet. The ^…$ token forces an exact match.

Boolean

type: boolean represents two values: true and false. Note that truthy and falsy values such as “true”, "", 0 or null are not considered boolean values.

Null

OpenAPI 3.0 does not have an explicit null type as in JSON Schema, but you can use nullable: true to specify that the value may be null. Note that null is different from an empty string "".

1
# Correct
2
type: integer
3
nullable: true
4

5
# Incorrect
6
type: null
7

8
# Incorrect as well
9
type:
10
  - integer
11
  - null

The example above may be mapped to the nullable types int? in C# and java.lang.Integer in Java. In objects, a nullable property is not the same as an optional property, but some tools may choose to map an optional property to the null value.

Arrays

Arrays are defined as:

1
type: array
2
items:
3
  type: string

Unlike JSON Schema, the items keyword is required in arrays. The value of items is a schema that describes the type and format of array items. Arrays can be nested:

1
# [ [1, 2], [3, 4] ]
2
type: array
3
items:
4
  type: array
5
  items:
6
    type: integer

and contain objects:

1
# [ {"id": 5}, {"id": 8} ]
2
type: array
3
items:
4
  type: object
5
  properties:
6
    id:
7
      type: integer

Item schema can be specified inline (as in the previous examples), or referenced via $ref:

1
# Array of Pets
2
type: array
3
items:
4
  $ref: "#/components/schemas/Pet"

Mixed-Type Arrays

Mixed-type arrays can be defined using oneOf:

1
# ["foo", 5, -2, "bar"]
2
type: array
3
items:
4
  oneOf:
5
    - type: string
6
    - type: integer

oneOf allows both inline subschemas (as in the example above) and references:

1
# Array of Cats and Dogs
2
type: array
3
items:
4
  oneOf:
5
    - $ref: "#/components/schemas/Cat"
6
    - $ref: "#/components/schemas/Dog"

An array of arbitrary types can be defined as:

1
type: array
2
items: {}

1
# [ "hello", -2, true, [5.7], {"id": 5} ]

Here, {} is the “any-type” schema (see below). Note that the following syntax for items is not valid:

1
# Incorrect
2
items:
3
  - type: string
4
  - type: integer
5

6
# Incorrect as well
7
items:
8
  type:
9
    - string
10
    - integer

Array Length

You can define the minimum and maximum length of an array like so:

1
type: array
2
items:
3
  type: integer
4
minItems: 1
5
maxItems: 10

Without minItems, an empty array is considered valid.

uniqueItems

You can use uniqueItems: true to specify that all items in the array must be unique:

1
type: array
2
items:
3
  type: integer
4
uniqueItems: true
5
# [1, 2, 3] – valid
6
# [1, 1, 3] – not valid
7
# [ ] – valid

Objects

An object is a collection of property/value pairs. The properties keyword is used to define the object properties – you need to list the property names and specify a schema for each property.

1
type: object
2
properties:
3
  id:
4
    type: integer
5
  name:
6
    type: string

Tip: In OpenAPI, objects are usually defined in the global components/schemas section rather than inline in the request and response definitions.

Required Properties

By default, all object properties are optional. You can specify the required properties in the required list:

1
type: object
2
properties:
3
  id:
4
    type: integer
5
  username:
6
    type: string
7
  name:
8
    type: string
9
required:
10
  - id
11
  - username

Note that required is an object-level attribute, not a property attribute:

1
type: object
2
properties:
3
  id:
4
    type: integer
5
    required: true # Wrong!
6

7
required: # Correct
8
  - id

An empty list required: [] is not valid. If all properties are optional, do not specify the required keyword.

Read-Only and Write-Only Properties

You can use the readOnly and writeOnly keywords to mark specific properties as read-only or write-only. This is useful, for example, when GET returns more properties than used in POST – you can use the same schema in both GET and POST and mark the extra properties as readOnly. readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses.

1
type: object
2
properties:
3
  id:
4
    # Returned by GET, not used in POST/PUT/PATCH
5
    type: integer
6
    readOnly: true
7
  username:
8
    type: string
9
  password:
10
    # Used in POST/PUT/PATCH, not returned by GET
11
    type: string
12
    writeOnly: true

If a readOnly or writeOnly property is included in the required list, required affects just the relevant scope – responses only or requests only. That is, read-only required properties apply to responses only, and write-only required properties – to requests only.

Nested Objects

An object can include nested objects:

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
        contact_info:
11
          # The value of this property is an object
12
          type: object
13
          properties:
14
            email:
15
              type: string
16
              format: email
17
            phone:
18
              type: string

You may want to split nested objects into multiple schemas and use $ref to reference the nested schemas:

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
        contact_info:
11
          $ref: "#/components/schemas/ContactInfo"
12

13
    ContactInfo:
14
      type: object
15
      properties:
16
        email:
17
          type: string
18
          format: email
19
        phone:
20
          type: string

Free-Form Object

A free-form object (arbitrary property/value pairs) is defined as:

1
type: object

This is equivalent to

1
type: object
2
additionalProperties: true

and

1
type: object
2
additionalProperties: {}

Number of Properties

The minProperties and maxProperties keywords let you restrict the number of properties allowed in an object. This can be useful when using additionalProperties or free-form objects.

1
type: object
2
minProperties: 2
3
maxProperties: 10

In this example, {"id": 5, "username": "trillian"} matches the schema, but {"id": 5} does not.

Files

Unlike OpenAPI 2.0, Open API 3.0 does not have the file type. Files are defined as strings:

1
type: string
2
format: binary # binary file contents

1
type: string
2
format: byte # base64-encoded file contents

depending on the desired file transfer method. For more information, see File Upload, Multipart Requests and Response That Returns a File.

Any Type

A schema without a type matches any data type – numbers, strings, objects, and so on. {} is shorthand syntax for an arbitrary-type schema:

1
components:
2
  schemas:
3
    AnyValue: {}

If you want to provide a description:

1
components:
2
  schemas:
3
    AnyValue:
4
      description: Can be any value - string, number, boolean, array or object.

The above is equivalent to:

1
components:
2
  schemas:
3
    AnyValue:
4
      anyOf:
5
        - type: string
6
        - type: number
7
        - type: integer
8
        - type: boolean
9
        - type: array
10
          items: {}
11
        - type: object

If the null value needs to be allowed, add nullable: true:

1
components:
2
  schemas:
3
    AnyValue:
4
      nullable: true
5
      description: Can be any value, including `null`.

Did not find what you were looking for? Ask the community
Found a mistake? Let us know