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 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:

NameTypeRemark
StringPrimitiveText field for short, un-formatted texts. While creating, it is also possible to set enumeration elements
BooleanPrimitiveType definition for truth values with the "true" or "false" property
NumberPrimitiveAllows you to save a number with decimal places. While creating, it is also possible to set enumeration elements
IntegerPrimitiveAllows you to save a number without decimal places. While creating, it is also possible to set enumeration elements
ObjectComplexAllows you to create an object with more than one property that are all of different types
ArrayComplexAllows you to create an array of items of an existing or new schema
OneOfComplexAllows 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

NameTypeRemark
FormatSelection Listdate, date-time, email, password, url
PatternStringThis pattern is used for validation within any modifying action by defining a regular expression
Min. lengthInteger
Max. lengthInteger

Number

NameTypeRemark
FormatSelection Listdouble, float
Min. valueNumberDefines the smallest valid value (minimum value) for a numeric property
Max. valueNumberDefines the largest valid value (maximum value) for a numeric property. If filled, it must be bigger or equal than the Min. value

Integer

NameTypeRemark
FormatSelection Listint32, int64
Min. valueNumberDefines the smallest valid value (minimum value) for a numeric property
Max. valueNumberDefines the largest valid value (maximum value) for a numeric property. If filled, it must be bigger or equal than the Min. value

Array

NameTypeRemark
Array itemsSelection ListShows a list of all existing (reusable) schemas that can be used as items in that array schema. This information is mandatory

OneOf

NameTypeRemark
OneOfSchemasListDefine 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

All types of (reusable) schemas can be edited either via the inline Edit capability in the Schemas tab or by using the inline Information capability and navigating to the Master Data section and using the Edit Master Data capability.

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

Note: 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

Tip: 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.

Tip: 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 PropertyIs a ListProperty to createSchema Type
Referencefalsereferenced schema propertymapped to an existing or new reusable schema
Referencetrueinline property of type arraymapped to an existing or new reusable array of object schema
External Referencefalsereferenced schema propertymapped to an existing or new reusable schema
External Referencetrueinline property of type arraymapped to an existing or new reusable array of object schema
Local Entityfalsereferenced schema propertymapped to an existing or new reusable object schema
Local Entitytrueinline property of type array mapped to an existing or new reusable array of objects schema
Currency-referenced schema propertymapped to an existing or new reusable schema
GeoPoint-referenced schema propertymapped to an existing or new reusable schema
Text-inline propertyprimitive type String
Text/Email-inline propertyprimitive type String
Text/URL-inline propertyprimitive type String
Boolean-inline propertyprimitive type Boolean
Date-inline propertyprimitive type String
Timestamp-inline propertyprimitive type String
Selection Element-inline propertyprimitive type String
Localized Text-referenced schema propertymapped to an existing or new reusable schema
Decimal-inline propertyprimitive type Number
Integer-inline propertyprimitive type Integer

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.

Tip: You can use properties and select an existing schema if you want to nest schemas into each other

Delete a schema

You can delete the schema by using the inline Delete capability or by using it within the Details view. Alternatively, you can use the Information capability to access the Details view and there you can use the Delete capability.

You will need to confirm the action before the selected schema is permanently deleted.

Note: You can only delete a schema if it is not in use.