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 edit schemas that
have been previously created 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.
Open the details form for a schema. For details of the areas in your API definition from where
you can edit 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
.
To return to the design form, click the Form icon
.
Procedure
You can configure the following schema settings:
-
Schema Name: Available if you are editing 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
To change the
name, click
Update, change the value in the field, then click
Save.
- Title: The schema title.
- Type: The schema data type; select one of the following:
-
- array
- boolean
- integer
- number
- object
- string
Note: If you change the type of an existing schema, any existing settings that are not relevant to
the new type are still retained in the OpenAPI source even though they are no longer displayed in
the user interface. You should therefore avoid porting a schema from one type to another but instead
either create a new schema or modify the OpenAPI source directly; to open the source editor, click
the
Source icon

.
- Additional schema settings dependent on the selected Type, as
follows:
- array:
- Max Items: The maximum allowed number of items in an array instance.
- Min Items: The minimum allowed number of items in an array
instance.
- Unique Items: If selected, all items in an array instance must be
unique.
- boolean: no type specific settings.
- integer:
- Format: An optional data type modifier. For more information, see Data
Types in the OpenAPI Specification.
- Multiple Of: Division of an integer instance by this value must result in
an integer.
- Maximum: An integer instance must be less than or equal to this
value.
- Exclusive Maximum: An integer instance must be strictly less than this
value.
- Minimum: An integer instance must be greater than or equal to this
value.
- Exclusive Minimum: An integer instance must be strictly greater than this
value.
- number:
- Format: An optional data type modifier. For more information, see Data
Types in the OpenAPI Specification.
- Multiple Of: Division of a number instance by this value must result in
an integer.
- Maximum: A number instance must be less than or equal to this value.
- Exclusive Maximum: A number instance must be strictly less than this
value.
- Minimum: A number instance must be greater than or equal to this
value.
- Exclusive Minimum: A number instance must be strictly greater than this
value.
- object
- Properties: To add properties to the schema, click
Add alongside the Properties section heading. You
configure a property by defining its schema with the schema editor.
To create the property, refer
to Creating a schema.
To further configure the property, follow
the steps on this page.
By defining properties, you can create more complex data structures.
For example, you could define an
Address
schema that has the following properties:
PROPERTY NAME |
PROPERTY TYPE |
street1 |
string |
street2 |
string |
city |
string |
state |
string |
zip_code |
string |
and then define a
BankBranch
schema that has the following properties, one of which
is a reference to the Address schema:
PROPERTY NAME |
PROPERTY TYPE |
address |
address |
type |
string |
id |
string |
- Max Properties: The number of properties in an object instance must be
less than or equal to this value.
- Min Properties: The number of properties in an object instance must be
greater than or equal to this value.
- Required Properties: An array of property names; every property name in
the array must be the name of a property in an object instance. To add a required property name,
click Add alongside the Required Properties section
heading, enter the name, then click Create.
- string:
- Format: An optional data type modifier. For more information, see Data
Types in the OpenAPI Specification.
- Pattern: A regular expression; a string instance must successfully match
the expression.
- Max Length: The maximum allowed number of characters in a string
instance.
- Min Length: The minimum allowed number of characters in a string
instance.
- Enum: An array of string values; a string instance must match one of the
array values. To add an enum value, click Add, enter the value, then click
Create.
- Description: An optional description of the schema. You can use
CommonMark syntax
for rich text representation.
- General settings; select the required options:
- Read Only: A property associated with this schema can be returned in a
response but should not be included in a request. For example, properties whose values are system
generated identifiers will be defined as Read Only because application
clients wouldn't be able to set these.
- Write Only: A property associated with this schema can be included in a
request but should not be returned in a response. For example, password properties are usually
defined as Write Only because application clients would supply these when
creating a user object but shouldn't be able see them when retrieving the object.
- Deprecated: The schema is deprecated and should be transitioned out of
usage.
- Example Value: An example value. Whatever you enter here is
displayed as-is in the Developer Portal.
- External Documentation: An external resource for extended
documentation; provide the following information:
- URL (required): The URL for the target documentation.
- Description: An optional description of the target documentation. You can
use CommonMark
syntax for rich text representation.
- Xml: Metadata that allows for more fine-tuned XML model
definitions; provide the following information:
- Name: Replaces the name of the element or attribute used for the
described schema property.
- Namespace: The URL of the namespace definition.
- Prefix: The prefix to be used for the Name.
- Attribute: Specifies whether the property definition translates to an
attribute instead of an element.
- Wrapped: For an array definition, Specifies whether the array is wrapped
(for example,
<books><book/><book/></books>
) or unwrapped
(<book/><book/>
).
- Click Save when done.
What to do next
If required, use the breadcrumb trail to navigate to another
location in the hierarchy of the object you are working on.