Schema Object in OpenAPI

The Schema Object represents any data type used as input or output in OpenAPI. Data types can be objects, arrays, or primitives such as string, number, integer, and boolean.

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 (opens in a new tab).

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 (opens in a new tab).

OpenAPI 3.1 changes the definition of two JSON Schema properties:

description - In OpenAPI this property may contain CommonMark syntax (opens in a new tab) 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	Type	Description
`discriminator`	Discriminator Object	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.
`xml`	XML Object	Adds details about how the schema should be represented as XML.
`externalDocs`	External Documentation Object	Points to external documentation for this schema.
`example`	Any	An example that satisfies this schema. Deprecated: Although valid, the use of `example` is discouraged. Use Examples instead.
`x-`	Extensions	Any number of extension fields can be added to the schema that can be used by tooling and vendors.
Arbitrary properties	Any	The schema object supports arbitrary properties without the `x-` 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.