Enhancing skills with OpenAPI specification properties

When you import an OpenAPI specification (OAS) properties, the properties in that OAS are used to create skills on watsonx Orchestrate. Some of these properties can change the method of the user interact with watsonx Orchestrate, then enhancing the user experience with watsonx Orchestrate.

See here how to enhance the user experience with OAS properties.

Configuring input and output data types

On requestBody and responses you can define schemas that describe values that the skills send and receive from API. These schemas are converted into inputs and outputs fields on watsonx Orchestrate.

watsonx Orchestrate supports the following data types in their schemas.

String

A text type, use type: string to configure an input or output as a string.

The image shows how a string type looks like on watsonx Orchestrate.

Data type string

The following example shows how to configure a string type.

{
  "properties": {
    "username": {
      "type": "string"
    }
  }
}

String can be modified to other types by using the format property. Use this property to modify strings to date, date-time, password, byte, binary, email, or url/uri formats on watsonx Orchestrate.

The image shows how a string type that is formatted looks like on watsonx Orchestrate.

String types

The following example shows how to use the format property.

{
  "properties": {
    "binary": {
      "type": "string",
      "format": "binary"
    },
    "date": {
      "type": "string",
      "format": "date"
    },
    "dateAndTime": {
      "type": "string",
      "format": "date-time"
    },
    "password": {
      "type": "string",
      "format": "password"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "url": {
      "type": "string",
      "format": "url/uri"
    },
    "byteFormat": {
      "type": "string",
      "format": "byte"
    }
  }
}

Number

A numeric type that includes integer and floating-point numbers. Use type: number to configure an input or output as a number.

The image shows how a number type looks like on watsonx Orchestrate.

Data type number

The following example shows how to configure a number type.

{
  "properties": {
    "number": {
      "type": "number"
    }
  }
}

Integer

A numeric type that includes only integer numbers. Use type: integer to configure an input or output as an integer.

The image shows how an integer type looks like on watsonx Orchestrate.

Data type integer

The following example shows how to configure an integer type.

{
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    }
  }
}

You can also use nullable: true property to enable null values as input or output.

Boolean

A true or false type. Use type: boolean to configure an input or output as a Boolean.

The image shows how a Boolean type looks like on watsonx Orchestrate.

Boolean field example

The following example shows how to configure a Boolean type.

{
  "properties": {
    "activateService": {
      "type": "boolean"
    }
  }
}

Array

An Array is a data structure type. You can use type: array and items: to configure an input or output array structure.

The image shows how an array type looks like on watsonx Orchestrate.

Data type array

The following example shows how to configure an array type.

{
  "properties": {
    "usersId": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      }
    }
  }
}

In arrays, you can use the oneOf property to create mixed-type arrays, minItems and maxItems properties to define the minimum and maximum length of the array, and uniqueItems to specify that all items in the array must be unique.

Object

An Object is a collection of property and value pairs. You can use type: object and properties: to configure an input or output as objects.

The image shows how an object type looks like on watsonx Orchestrate.

Data type integer

The following example shows how to configure an object type.

{
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "username": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}

In objects, you can use required to define the required properties of the objects, readOnly and writeOnly to mark specific properties to read or write only, minProperties and maxProperties to configure the number of properties allowed in an object.

Date

Depending on your API, you can configure dates as string or integer data types in an OAS file.

For dates in string data type, use the format property to convert the string data type to the date or date-time data type. For more information about string data type, see String.

According to your API, you can configure a string data type without the format property. In that case, it's good to give descriptions of what the expected date format for your API.

The image shows how the string dates look like on watsonx Orchestrate.

String dates

The following example shows how to use the string data type as date.

{
  "properties": {
    "datePlainText": {
      "type": "string",
      "description": "The expected value is: Month DD, YYYY"
    },
    "date": {
      "type": "string",
      "format": "date"
    },
    "dateAndTime": {
      "type": "string",
      "format": "date-time"
    }
  }
}

You can also use the integer data type to configure dates in one OAS file. This method is normally used to configure dates in EPOCH format.

The image shows how the integer dates look like on watsonx Orchestrate.

Integer dates

The following example shows how to use the integer data type as date.

{
  "properties": {
    "date": {
      "type": "integer"
    }
  }
}

You can use both methods, string and integer, to return dates in EPOCH format. In that case, to show that EPOCH outputs date in a human readable format, configure the format property as epoch.

When you configure an output as EPOCH format, the date is shown by following the structure YYYY-MM-DD. However, the value continues in the EPOCH format if you use that date output as input for another skill in skill flows or skill sequencing.

The image shows how an EPOCH date output looks like on watsonx Orchestrate.

EPOCH date output

The following example shows how to configure the format property as epoch.

{
  "properties": {
    "epochDate": {
      "type": "string",
      "format": "epoch"
    }
  }
}

Uploading files as input

Many skills might potentially require users to upload files as part of the skill, for example, uploading an I-9 form. To do it, the input form must display a suitable file upload widget to the user. The uploaded content can then be passed to the API.

Uploading a single file

To create a single file upload, you must define a property with type: "string" and format: binary.

This configuration presents a file upload widget to the user that accepts a single file and sends a JSON payload to the API with the content of the uploaded file as a base64 encoded string.

The following image shows how the upload a single file field looks like on watsonx Orchestrate.

Example of single file upload

The following example shows how to configure the input to upload a single file.

{
  "properties": {
    "useri9Form": {
      "type": "string",
      "format": "binary"
    }
  }
}

Uploading multiple files

You can create a multifile upload widget to allow users to upload any number of files to the API. To do it, configure an array object.

The following image shows how the upload multiple files field looks like on watsonx Orchestrate.

Example of multiple files uploads

The following example shows how to configure the input to upload multiple files.

{
  "properties": {
    "redundant": {
      "type": "boolean",
      "x-ibm-show": false
    },
    "userDocuments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    }
  }
}

The field redundant is provided because without it, an empty array is immediately provided, which is a valid value for an array. The field redundant is not marked as required. Therefore, you need to expand it to see it in the form. The field redundant can be hidden from the form with the x-ibm-show property.