Creating a schema

Schemas provide developers with information about the request they should make, or the response they should expect to receive, when calling an API operation. You can create schemas in various places in your API definition.

Before you begin

Note: Schemas are compiled before they are used for validation. Because the compilation process is longer than the validation process, the compiled schema artifacts are stored in a cache. The limited capacity of the cache can cause older entries to be evicted from the cache when newer entries are added. Schemas whose artifacts have been evicted from the cache must be recompiled, which can cause significant delays in validation.
Launch the schema creation window. For details of the areas in your API definition from where you can create a schema, see the following topics:

About this task

Note:
  • This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.
  • OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
  • For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM® API Connect.

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

At any time, you can switch directly to the underlying OpenAPI YAML source by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.

Procedure

  1. Create the schema; you can either create a schema from scratch, or you can reference a schema that is defined in a schema component.
    • To create the schema from scratch, provide the following information on the Definition tab:
      • Schema Name: If you are creating a schema component, this name defines a key that enables this schema to be referenced from elsewhere in the API definition; the reference has the following format:
        #/components/schemas/Name
      • Title: The schema title.
      • Type: The schema data type; select one of the following:
        • array
        • boolean
        • integer
        • number
        • object
        • string
      • Description: An optional description of the schema. You can use CommonMark syntax for rich text representation.
      • Select the following options as required:
        • Read Only: A property associated with this schema can be sent in a response but should not be sent in a request.
        • Write Only: A property associated with this schema can be sent in a request but should not be sent in a response.
        • Deprecated: The schema is deprecated and should be transitioned out of usage.
    • To reference a schema that is defined in another schema component, provide the following information on the Reference tab:.
      • Schema Name: If you are creating a schema component, this name defines a key that enables this schema to be referenced from elsewhere in the API definition; the reference has the following format:
        #/components/schemas/Name
      • Reference from: Select a reference to a schema component.
  2. Click Create.
    The schema details are displayed for further editing; see Editing a schema.