Editing 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 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 OpenAPI Source icon. To return to the design form, click the Form icon 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 OpenAPI source editor 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:
    • Nullable: Properties associated with this schema can be null.
    • 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.