Defining schema components

Schema components define reusable schemas that provide developers with information about the request they should make, or the response they should expect to receive, when calling an API operation.

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.

An API created in OpenAPI 3.0 includes a section where API payload definitions are defined. The payload definitions describe the structure of data transmitted in API requests and responses, utilizing a specialized JSON schema variant specific to OpenAPI. Each payload definition corresponds to a schema, which lists the expected data fields. These data fields are represented as properties within the schema and include a set of attributes that describe their type, permissible values, mandatory status, and other characteristics. Although numerous attributes are available, the majority of them are infrequently utilized.

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

To make use of a schema component, you reference it from elsewhere in your API definition. You can reference a schema from the following locations:

An API Path parameter; see Defining parameters for a Path.
An API operation parameter; see Defining parameters for an operation.
The request body of an API operation; see Defining the request body for an operation.
An API operation response; see Defining responses for an operation.

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

Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
Expand Components then, if there are already one or more schemas components defined, expand Schemas.
You can create a new schema component, or edit any existing schema component.
- To create a schema component, click the add icon alongside Schemas, then refer to Creating a schema component.
- To edit an existing schema component, click the schema component name in the navigation pane, then refer to Editing a schema component.