Modelling Schemas

The Solution Designer in IBM Industry Solutions Workbench is connected to a central schema registry and provides various capabilities to manage its schemas. You can find all defined schemas by visiting the Schemas page in the Solution Designer using the navigation bar.

Create a new schema

To create a new schema, you can use the button "Create Schema" on the Schemas page.

Define schema meta data

In the first step, the following schema meta data has to be defined:

  • Identifier: The identifier of the schema, which has to be unique within the group (required)
  • Name: The name of the schema used for displaying purposes (required)
  • Group: The group in which the schema will be created. Grouping relevant schemas together can help to keep the overview. You can choose either an existing group or add a new one. If no group is defined, the "default" group is used automatically
  • Version: The initial version number of the schema. If not provided, the server will generate a new, unique version number. It is recommended to create a new schema always with version "1"
  • Tags: Tags to group schemas together which can help to keep the overview across multiple schemas
  • Description: The description of the schema used to add some notes on the purpose of the schema

Define schema structure

In the second step, the schema structure has to be defined. A schema is always a complex structure, which consists out of multiple properties. Each property has a name and a type and can have additional attributes (e. g. for validation).

The properties of the schema can be defined either through the Modelling Editor or the Expert Editor.

Using the Modelling Editor you can easily add new properties by using the "Add" capability in the UI. It allows to specify all details around the properties, e. g. type, format, minimum and maximum length in a comfortable way. Currently String, Boolean, Number and Integer properties are supported this way. In case more complex types like objects or arrays are needed, it is recommended to switch to the Expert Editor. There, the integrated JSON editor can be used to define the structure in the format of JSON Schema 2019-09.

You can also use the Open after creation checkbox to open the Schema for further editing after creating.

Create a new version of a schema

As requirements change over time, it is necessary that the payload structure of events can evolve further over time as well. Since schemas are used as a reliable contract between producers and consumers, it is not allowed that they are changed after they have been published. Instead, a new version of the schema has to be created and published.

To create a new version, you have to open the schema in the Schemas page. On the schema instance page you can find all published versions of the schema. By clicking on Create new version the action for creating the new version opens. In the first step you can define the new version number for your schema. It is recommended to increase the latest version number by one. In the second step you can define the properties of the schema by either using the Modelling Editor or the Expert Editor.

When creating a new version of a schema, the compatibilty rules defined in your schema registry will be applied. This could e. g. lead to the fact that breaking changes in new versions will not be allowed and you will be prevented from creating the new version.

Schema usages

On the schema instance page the usages section shows in which Events the displayed version of the schema is used.

Note:

You can select the version that is displayed by using the Versions tab and select the version in the table.

Delete schema

On the schema instance page, you can delete the schema from the schema registry. The deletion of the schema will delete all versions and might have impact on existing projects where the schema is used. Therefore, it is recommended to only delete schemas for which it is ensured that they are not in use by any service.

Note:

Deleting single versions of a schema is not possible. Only the whole schema can be deleted.

Define schema in schema registry directly

In general, IBM Industry Solutions Workbench as well supports schemas, which were defined in the schema registry by using different tooling (e. g. Apicurio Studio). As soon as a schema or a new version is created in the schema registry, it appears in the Schemas page in the Solution Designer and can be used within events.

Restrictions:

  • format has to be JSON Schema 2019-09
  • only properties of type Boolean, String, Number, Integer, Array and Object are currently allowed