OAS 3 This guide is for OpenAPI 3.0.

Data Types

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

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): 
# Incorrect
type:
  - string
  - integer
Mixed types can be described using oneOf and anyOf, which specify a list of alternate types: 
# Correct
oneOf:
  - type: string
  - type: integer
See also Any Type.

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: 
type: integer
minimum: 1
maximum: 20
By default, the minimum and maximum values are included in the range, that is: 
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: 
type: number
minimum: 0
exclusiveMinimum: true
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: 
type: integer
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. 
type: number
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: 
type: string
String length can be restricted using minLength and maxLength: 
type: string
minLength: 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: 
ssn:
  type: string
  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 "". 
# Correct
type: integer
nullable: true

# Incorrect
type: null

# Incorrect as well
type:
  - integer
  - 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: 
type: array
items:
  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, 2], [3, 4] ]
type: array
items:
  type: array
  items:
    type: integer
and contain objects: 
# [ {"id": 5}, {"id": 8} ]
type: array
items:
  type: object
  properties:
    id:
      type: integer
Item schema can be specified inline (as in the previous examples), or referenced via $ref: 
# Array of Pets
type: array
items:
  $ref: '#/components/schemas/Pet'

Mixed-Type Arrays

Mixed-type arrays can be defined using oneOf: 
# ["foo", 5, -2, "bar"]
type: array
items:
  oneOf:
    - type: string
    - type: integer
oneOf allows both inline subschemas (as in the example above) and references: 
# Array of Cats and Dogs
type: array
items:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
An array of arbitrary types can be defined as: 
type: array
items: {}

# [ "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: 
# Incorrect
items:
  - type: string
  - type: integer

# Incorrect as well
items:
  type: 
    - string
    - integer

Array Length

You can define the minimum and maximum length of an array like so: 
type: array
items:
  type: integer
minItems: 1
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: 
type: array
items:
  type: integer
uniqueItems: true

# [1, 2, 3] – valid
# [1, 1, 3] – not valid
# [ ] – 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. 
type: object
properties:
  id:
    type: integer
  name:
    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: 
type: object
properties:
  id:
    type: integer
  username:
    type: string
  name:
    type: string
required:
  - id
  - username
Note that required is an object-level attribute, not a property attribute: 
type: object
properties:
  id:
    type: integer
    required: true  # Wrong!

required:           # Correct
  - 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. 
type: object
properties:
  id:
    # Returned by GET, not used in POST/PUT/PATCH
    type: integer
    readOnly: true
  username:
    type: string
  password:
    # Used in POST/PUT/PATCH, not returned by GET
    type: string
    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: 
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        contact_info:
          # The value of this property is an object
          type: object
          properties:
            email:
              type: string
              format: email
            phone:
              type: string
You may want to split nested objects into multiple schemas and use $ref to reference the nested schemas: 
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        contact_info:
          $ref: '#/components/schemas/ContactInfo'

    ContactInfo:
      type: object
      properties:
        email:
          type: string
          format: email
        phone:
          type: string

Free-Form Object

A free-form object (arbitrary property/value pairs) is defined as: 
type: object
This is equivalent to 
type: object
additionalProperties: true
and 
type: object
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. 
type: object
minProperties: 2
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: 
type: string
format: binary  # binary file contents
or 
type: string
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: 
components:
  schemas:
    AnyValue: {}
If you want to provide a description: 
components:
  schemas:
    AnyValue:
      description: Can be any value - string, number, boolean, array or object.
The above is equivalent to: 
components:
  schemas:
    AnyValue:
      anyOf:
        - type: string
        - type: number
        - type: integer
        - type: boolean
        - type: array
          items: {}
        - type: object

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

components:
  schemas:
    AnyValue:
      nullable: true
      description: Can be any value, including `null`.

  

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