Schemas
A schema represents a data type that can be used by other components. Schemas can be of primitive or complex type.
Create a schema
You can create a new (reusable) schema by using the Create schema capability on the Schemas tab of the API Namespace's Overview page.
You must provide the following information for every schema:
- Type: Defines the type of the schema to be created (required)
- Local Identifier: Identifier of the schema. This value must be unique within the namespace and cannot be changed afterwards. Please note, that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
- Title: Title of the schema (optional)
- Description: Description of the schema (optional)
Schema types
The following types are available:
| Name | Type | Remark |
|---|---|---|
| String | Primitive | Text field for short, un-formatted texts. While creating, it is also possible to set enumeration elements |
| Boolean | Primitive | Type definition for truth values with the "true" or "false" property |
| Number | Primitive | Allows you to save a number with decimal places. While creating, it is also possible to set enumeration elements |
| Integer | Primitive | Allows you to save a number without decimal places. While creating, it is also possible to set enumeration elements |
| Object | Complex | Allows you to create an object with more than one property that are all of different types |
| Array | Complex | Allows you to create an array of items of an existing or new schema |
| OneOf | Complex | Allows you to create a type that could take the form of exactly one schema out of a list of predefined sub schemas |
Defining type specific behavior
While creating a schema you can define additional properties based on the type of the schema:
Boolean, Object
No specific information.
String
| Name | Type | Remark |
|---|---|---|
| Format | Selection List | date, date-time, email, password, url |
| Pattern | String | This pattern is used for validation within any modifying action by defining a regular expression |
| Min. length | Integer | |
| Max. length | Integer |
Number
| Name | Type | Remark |
|---|---|---|
| Format | Selection List | double, float |
| Min. value | Number | Defines the smallest valid value (minimum value) for a numeric property |
| Max. value | Number | Defines the largest valid value (maximum value) for a numeric property. If filled, it must be bigger or equal than the Min. value |
Integer
| Name | Type | Remark |
|---|---|---|
| Format | Selection List | int32, int64 |
| Min. value | Number | Defines the smallest valid value (minimum value) for a numeric property |
| Max. value | Number | Defines the largest valid value (maximum value) for a numeric property. If filled, it must be bigger or equal than the Min. value |
Array
| Name | Type | Remark |
|---|---|---|
| Array items | Selection List | Shows a list of all existing (reusable) schemas that can be used as items in that array schema. This information is mandatory |
OneOf
| Name | Type | Remark |
|---|---|---|
| OneOfSchemas | List | Define a list of sub schemas Minimum one object schemas has to be chosen. This information is mandatory |
| Discriminator | Discriminators are property names used to distinguish between the sub schemas of the oneOf schema. When defining a property name as discriminator, this property will be automatically generated. The discriminator name must be unique within an object. The discriminator value is always set automatically to refer to the corresponding schema type. The discriminator hast to start with a lower case letter and can contain letters, numbers or underscores. This information is mandatory |
Edit a schema
You can edit all types of (reusable) schemas by clicking the Edit schema details button in the Schema Details section on the schema's instance page. Alternatively, you can use the Edit capability of each table row on the Schemas tab of a api namespace's Overview page.
Within these actions you can adjust all schema specific properties (see chapter before) except of the type of schema and its local identifier.
For some schema types there is additional information to maintain described as the following:
Managing a String schema
You can add enumeration elements to a string by using the inline Information capability and navigating to the Enumeration Elements section and using the Add capability. The only property needed to add an enumeration element is the key of the new enumeration element.
You can remove an enumeration element by using the inline or overhead Remove capability.
Managing an Object schema
Properties can be added, edited and removed only in object schemas.
There are two options when adding a property: Import or Add properties.
Import properties
You can import properties of entities that you already created in a Domain Namespace or in an Integration Namespace.
If you want to import properties from an existing entity you have to select the entity first. The import dialog provides a drop-down with all available entities. After selection, you will be presented with a table that lists all available properties. In case the selected entity has no properties at all, you will see a hint.
Now you can select one or more properties which will get added to your schema after clicking on the Import button of the dialog.
You also have the option to edit a property's name and set it as a required property.
Mapping rules when importing properties:
| Domain Namespace Property | Is a List | Property to create | Schema Type |
|---|---|---|---|
| Reference | false | referenced schema property | mapped to an existing or new reusable schema |
| Reference | true | inline property of type array | mapped to an existing or new reusable array of object schema |
| External Reference | false | referenced schema property | mapped to an existing or new reusable schema |
| External Reference | true | inline property of type array | mapped to an existing or new reusable array of object schema |
| Local Entity | false | referenced schema property | mapped to an existing or new reusable object schema |
| Local Entity | true | inline property of type array mapped to an existing or new reusable array of objects schema | |
| Currency | - | referenced schema property | mapped to an existing or new reusable schema |
| GeoPoint | - | referenced schema property | mapped to an existing or new reusable schema |
| Text | - | inline property | primitive type String |
| Text/Email | - | inline property | primitive type String |
| Text/URL | - | inline property | primitive type String |
| Boolean | - | inline property | primitive type Boolean |
| Date | - | inline property | primitive type String |
| Time | - | inline property | primitive type String |
| Timestamp | - | inline property | primitive type String |
| Selection Element | - | inline property | primitive type String |
| Localized Text | - | referenced schema property | mapped to an existing or new reusable schema |
| Decimal | - | inline property | primitive type Number |
| Integer | - | inline property | primitive type Integer |
| Long | - | inline property | primitive type Integer (format: int64) |
Add properties
Inline are the properties that are created from scratch with a new schema definition that has not been created before. After the creation of an inline property, the newly created property will not be reusable.
Inline properties are defined using the following master data:
- Name: This is the name of the inline property. It is unique within a namespace. Please note, that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming inline entities! Furthermore, names may not begin with a digit and the first character must be in lower case. The identifier can not be changed after creation (required)
- Property Type: This is the schema type of the property that is being created. It can be one of the primitive types (String, Boolean, Number, Integer), an Array, a OneOf or it can reference an existing schema that was previously created (required)
- Required: This is a Boolean. If it is checked, then the property is required, otherwise it is optional (optional)
The rest of the properties depend on the type of the chosen schema.
You can use properties and select an existing schema if you want to nest schemas into each other
Delete a schema
You can delete a schema by clicking the Delete schema button in the upper right corner of the schema instance page. Alternatively, you can use the Delete capability of each table row on the Schemas tab of a api namespace's Overview page.
You will need to confirm the action before the selected schema is permanently deleted.
You can only delete a schema if it is not in use.