Important → Please check out the breaking changes as of 13th December 2019

Schema definition

Your personal, tenant-specific schema, consists of unchangeable system properties, and the global schema. It determines the attributes and properties that objects must or may have. This basic information provides details about the general structure of the schema. Note that the mentioned expect a schema in XML format.

Endpoint Overview ↑

→ "Try it out - API Component "Admin"
→ check GitHub Python calls | Java Script calls | Java calls | Postman collection

Retrieve your Schema ↑

You can retrieve your schema by sending a GET request to the URL /admin/schema ("Get the raw tenant schema" endpoint). This schema contains your tenant-specific, user-defined object types, properties, and so on. It does not contain any system types, meaning you can upload it as it is without the system behaving differently afterwards. Only the version number of the schema and the modification date would change. Underneath the tenant-specific schema lies a preconfigured global schema which can not be be altered. To retrieve a complete schema consisting of the global schema and the additions specific to the tenant of the user that requests it, use /schema/native ("Get the applied tenant schema" endpoint).

Request getSchemaRequest = new Request.Builder()
		.header("Ocp-Apim-Subscription-Key", key)
		.url(baseUrl + "/admin/schema")
		.get()
		.build();

The OkHttpClient instance makes it easy to write the schema to a file.

try(FileOutputStream fos = new FileOutputStream("activeSchema.xml")) {
    Response activeSchemaResponse = client.newCall(getSchemaRequest).execute();
    byte[] bytes = activeSchemaResponse.body().bytes();
    fos.write(bytes);
}

Responses

Validate your Schema ↑

You use a POST request for the URL /admin/schema/validate to verify that your modified schema is valid ("Validate a schema" endpoint). This requires an XML schema; in the example, under the path ./schemaToValidate.xml. The schema is sent as a multipart in the body of the request.

String filename = "./schemaToValidate.xml";
RequestBody requestBody = new MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("file", "schema.xml", RequestBody.create(MediaType.parse("application/xml; charset=utf-8"), new File(filename)))
        .build();
Request validateSchemaRequest = new Request.Builder()
	.header("Ocp-Apim-Subscription-Key", key)
        .url(baseUrl + "/admin/schema/validate")
        .post(requestBody)
        .build();

The response to this request contains an HTTP status code and the validation result in JSON format. You can simply output this to the console after the request was called using an OkHttpClient instance.

Response validationResponse = client.newCall(validateSchemaRequest).execute();
System.out.println(validationResponse.code());
String validationResponseAsString = validationResponse.body().string();
System.out.println(validationResponseAsString);

In the case of a valid schema, the response contains the HTTP status code 200 and the validation result is an empty list, meaning it does not contain any validation errors.

{
    "validationErrors": []
}

If, however, the schema is not valid, the response contains the HTTP status code 422 and there is at least one validation error.

{
    "validationErrors": [{
        "message": "Invalid property reference 'name' in type definition 'email'."
    }]
}

Update your Schema ↑

To bring in your schema modifications update your tenant-specific schema using the "Update the tenant schema" endpoint. This endpoint validates your new schema first, before it will completely overwrite the existing one.

Responses

Schema Structure ↑

An object must have one and only one object type. The object type classifies the object and defines the properties that the object must have or is allowed to have (properties may be optional). The schema defines a set of object types and a set of properties. There are furthermore some metadata like 'version' or 'lastModificationDate ', whose values are provided by the system.

<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v5.0/ dmsCloud-schema.xsd">
        <propertyStringDefinition>
            <id>from</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>to</id>
            <propertyType>string</propertyType>
            <cardinality>multi</cardinality>
            <required>true</required>
        </propertyStringDefinition>
	<propertyStringDefinition>
            <id>subject</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
            <defaultValue>hello</defaultValue>
            <maxLength>20</maxLength>
	    <minLength>4</minLength>
	</propertyStringDefinition>
	<propertyDateTimeDefinition>
            <id>received</id>
            <propertyType>datetime</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyDateTimeDefinition>
	<typeDocumentDefinition>
            <id>email</id>
            <baseId>system:document</baseId>
            <propertyReference>from</propertyReference>
            <propertyReference>to</propertyReference>
            <propertyReference>received</propertyReference>
	    <contentStreamAllowed>required</contentStreamAllowed>
        </typeDocumentDefinition>
</schema>

By default the maximum number of property definitions in a tenant-specific schema is 20. A system integrator can change this limit via the parameter schema.tenant.properties.limit in the system service. If you want to increase this limit it is recommended to increase the maximum number of fields in your elasticsearch index as well.

Type-Ids ↑

In every property definition and every object type definition the attribute id is required. It is used to identify the object type or property. An id is a string of at most 63 characters and must match the regular expression([a-zA-Z][a-zA-Z0-9]*:)?[a-zA-Z][a-zA-Z0-9]*.

Type-ids are also used as the name of the type, e.g. in query operations. Hence, it is recommended to choose meaningful values for type-ids.

The part before the ':' is the prefix. In tenant-specific types the prefix is always "ten"+<tenant name>. Almost always you can omit the prefix when designing a schema or importing objects or creating search queries. The prefix is added automatically.

Property Definitions ↑

All property definitions have the following attributes.

Depending on the property-type a property can have specific attributes.

Integer Property Definitions

DateTime Property Definitions

Decimal Property Definitions

Decimal properties support values of 64-bit precision (IEEE 754).

String Property Definitions

Table Property Definitions

The column types of a table property are defined by a list of property definitions inside the table property definition. Each column property definition has its own attributes, such as required or default value. The values are applied to each row entry. The cardinality of a column property definition must be single.

Table properties differ depending on the value of the property queryable. If queryable is false, the table must not appear in "where" clauses in search queries. However, you can still find objects using full-text conditions on values stored in the table (query keyword 'CONTAINS'). If queryable is true, you can apply more precise search queries to the table, but you will need more disk space to store objects.

The number of rows and columns of a table property definition is limited to a maximum of 512 columns and 1024 rows.

<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v5.0/ dmsCloud-schema.xsd">
        <propertyTableDefinition>
            <id>aTableProperty</id>
            <propertyType>table</propertyType>
            <cardinality>single</cardinality>
            <required>false</required>
            <propertyStringDefinition>
                <id>col0</id>
                <propertyType>string</propertyType>
                <cardinality>single</cardinality>
                <required>false</required>
            </propertyStringDefinition>
            <propertyIntegerDefinition>
                <id>col1</id>
                <propertyType>integer</propertyType>
                <cardinality>single</cardinality>
                <required>false</required>
            </propertyIntegerDefinition>
            <propertyDateTimeDefinition>
                <id>col2</id>
                <propertyType>datetime</propertyType>
                <cardinality>single</cardinality>
                <required>false</required>
            </propertyDateTimeDefinition>
            <propertyDecimalDefinition>
                <id>col3</id>
                <propertyType>decimal</propertyType>
                <cardinality>single</cardinality>
                <required>false</required>
            </propertyDecimalDefinition>
    </propertyTableDefinition>
</schema>

Object Type Definitions ↑

There are different groups of object type definitions.

•  document object types
•  folder object types
•  secondary object types

In a schema all object type definitions must appear in this order. First all document object type definitions, than all folder object type definitions and so on.

All object type definitions have the following attributes.

A tenant-specific object type can have references to both tenant-specific and global properties.

Document Object Type Definitions

Document object types are the elementary object types. To store objects with content, the object's type must be a document type.

Document object type definitions have the following specific attributes.

Folder Object Type Definitions

Folder objects cannot have content. Objects can be assigned to a folder object. Then the folder object is the parent of the objects and the objects become the children of the folder object.

<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v5.0/ dmsCloud-schema.xsd">
        <propertyStringDefinition>
            <id>str1</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>str2</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
	<propertyStringDefinition> 
		<id>str3</id> 
		<propertyType>string</propertyType>
		<cardinality>single</cardinality>
		<required>true</required>
	</propertyStringDefinition>
        <typeDocumentDefinition>
            <id>documentType1</id>
            <baseId>system:document</baseId>
            <propertyReference>str1</propertyReference>
            <contentStreamAllowed>required</contentStreamAllowed>
            </typeDocumentDefinition>
    	<typeFolderDefinition>
    	    <id>folderA</id>
            <baseId>system:folder</baseId>
       	    <propertyReference>str1</propertyReference>
            <propertyReference>str2</propertyReference>
    	</typeFolderDefinition>
    	<typeFolderDefinition>
            <id>folderB</id>
            <baseId>system:folder</baseId>
            <propertyReference>str1</propertyReference>
            <propertyReference>str2</propertyReference>
            <propertyReference>str3</propertyReference>
    	</typeFolderDefinition>
</schema>

Secondary Object Type Definitions

Secondary object types are abstract. This means that secondary object types cannot be instantiated. Secondary object types allow you to design a more complex schema. In a way the concept of secondary object types is similar to the concept of inheritance.

Secondary object types can be used to group properties and then assign these property groups to other object types. Like other object types, a secondary object type can have references to properties. Document object types can in turn reference secondary object types, which gives them their properties.

Document object types have a property system:secondaryObjectTypeIds that contains the secondary object types associated with the document object type in the schema. This allows secondary object types to be taken into account during the search. The property system:secondaryObjectTypeIds is set by the repository using the schema.

Secondary object types can also be without properties. Their use can then be understood as categorization of document types (tagging).

<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v5.0/ dmsCloud-schema.xsd">
        <propertyStringDefinition>
            <id>str1</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>str2</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>str3</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <typeDocumentDefinition>
            <id>documentType1</id>
            <baseId>system:document</baseId>
            <propertyReference>str1</propertyReference>
            <contentStreamAllowed>required</contentStreamAllowed>
            <secondaryObjectTypeId>secondaryA</secondaryObjectTypeId>
        </typeDocumentDefinition>
        <typeSecondaryDefinition>
            <id>secondaryA</id>
            <baseId>system:secondary</baseId>
            <propertyReference>str2</propertyReference>
        </typeSecondaryDefinition>
        <typeSecondaryDefinition>
            <id>secondaryB</id>
            <baseId>system:secondary</baseId>
            <propertyReference>str2</propertyReference>
            <propertyReference>str3</propertyReference>
        </typeSecondaryDefinition>
</schema>

Consider the example schema. If a document of type documentType1 is created, it may have values for the properties str1 and str2. For str1 this is obvious, because there is a reference to str1 in the definition of documentType1. For str2 there is no direct reference, but the definition of documentType1 has a reference to the secondary object type secondaryA and secondaryA has a reference to str2.

Furthermore, properties induced by secondary object types are treated like "normal" properties in a document. The attributes of a property are respected. For example, a document of type documentType1 not only may have a value for str2, it must have a value, because str2 is a required property. It makes no difference, if a document type references the property types directly or indirectly via a secondary object type.

In the metadata of a document you can not see anymore, if a property is referenced directly or indirectly in the schema. All properties are plain in the properties-list. For example, the metadata of a document of documentType1 may look like this:

{
    "objects": [
        {
            "properties": {
                "system:objectId": {
                    "value": "7bce6618-2b0e-4abf-af26-e4137e6b0461"
                },
                "system:baseTypeId": {
                    "value": "system:document"
                },
                "system:objectTypeId": {
                    "value": "documentType1"
                },
                "system:secondaryObjectTypeIds": {
                    "value": [
                        "secondaryA"
                    ]
                },
                <...>
                "str1": {
                    "value": "abc"
                },
                "str2": {
                    "value": "def"
                }
            },
            "contentStreams": [
                <...>
            ]
        }
    ]
}

System Properties ↑

In addition to the properties assigned to the object types in the schema, each object type has a set of system properties (e.g. system:objectId, system:createdBy, system:creationDate). The values of system properties are set by the system.