Skip to Content
OpenAPI HubData Types

Data Types in OpenAPI

The Schema Object represents any data type used as input or output in OpenAPI. The standard supports the following data types:

  • Strings - A sequence of characters. (dates, times, passwords, byte, and binary data are considered strings)
  • Numbers - A number, either integer or floating-point.
  • Booleans - A true or false value.
  • Arrays - A collection of other data types.
  • Objects - A collection of key-value pairs.
  • Enums - A fixed list of possible values.
  • Null - A null value.

Schema objects are sometimes referred to as models, data types, or simply, schemas. This is because schema types are used to model complex data types used by an API.

The Schema Object is based on and extends the JSON Schema Specification Draft 2020-12 .

OpenAPI 3.1 uses all vocabularies from JSON Schema 2020-12, except for Format Assertion.

For an overview of all JSON Schema properties, see JSON Schema Docs > JSON Schema 2020-12 .

OpenAPI 3.1 changes the definition of two JSON Schema properties:

  • description - In OpenAPI this property may contain CommonMark syntax  to provide a rich description.
  • format - OpenAPI extends JSON Schema data types by adding additional formats. See Data Type Formats.

OpenAPI adds another vocabulary to JSON Schema with the following properties:

Field Name
Description
A discriminator object describes how to differentiate between related schemas based on the value of a field in a request or response. See Composition and Inheritance.
Description
Adds details about how the schema should be represented as XML.
Description
Points to external documentation for this schema.
Type
Any
Description
An example that satisfies this schema. Deprecated: Although valid, the use of
is discouraged. Use Examples instead.
Description
Any number of extension fields can be added to the schema that can be used by tooling and vendors.
Arbitrary properties
Type
Any
Description
The schema object supports arbitrary properties without the
prefix. This is discouraged in favor of Extensions.

The example below illustrates three schema objects: IngredientProductCode, Ingredient, and IngredientType.

components:
  schemas:
    IngredientProductCode:
      description: The product code of an ingredient, only available when authenticated.
      type: string
      examples:
        - "AC-A2DF3"
        - "NAC-3F2D1"
        - "APM-1F2D3"
    Ingredient:
      type: object
      properties:
        name:
          description: The name of the ingredient.
          type: string
          examples:
            - Sugar Syrup
            - Angostura Bitters
            - Orange Peel
        type:
          $ref: "#/components/schemas/IngredientType"
        stock:
          description: The number of units of the ingredient in stock, only available when authenticated.
          type: integer
          examples:
            - 10
            - 5
            - 0
          readOnly: true
        productCode:
          $ref: "#/components/schemas/IngredientProductCode"
        photo:
          description: A photo of the ingredient.
          type: string
          format: uri
          examples:
            - https://speakeasy.bar/ingredients/sugar_syrup.jpg
            - https://speakeasy.bar/ingredients/angostura_bitters.jpg
            - https://speakeasy.bar/ingredients/orange_peel.jpg
      required:
        - name
        - type
    IngredientType:
      description: The type of ingredient.
      type: string
      enum:
        - fresh
        - long-life
        - packaged

JSON Schema and OpenAPI

OpenAPI 3.0 was not totally compatible with JSON schema. That caused, and continues to cause, issues in tooling support. Fortunately, OpenAPI 3.1 is now a superset of JSON Schema, meaning compatibility with any valid JSon Schema document.

Last updated on