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).

Retrieving the Schema
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.

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

Status Code Meaning
200 OK
401 Unauthorized
403 Forbidden

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.

Validating a Schema
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.

Console Output of the Validation Result
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.

Result of a Successful Validation
{
    "validationErrors": []
}

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

Result of an Unsuccessful Validation
{
    "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

Status Code Meaning
200 OK
401 Unauthorized
422 Schema contains Errors

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.

A valid example schema
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v4.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v4.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>enaio: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.

Typ-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.

Attribute Type Required Description
id String yes The type-id of the property. It uniquely identifies the property in the schema.
localNamespace URI no By using namespaces, it is possible to form groups of properties and object types.
description String no Describes the property.
propertyType Enum yes This indicates the type of this property. The following types are supported:
  • boolean
  • integer
  • datetime
  • decimal
  • string
  • table
  • id
cardinality Enum yes

Defines whether the property can have at most one or an arbitrary number of values. Possible values are single and multi.

required Boolean yes If true, then there must be at least one value of this property in the object. If a property is required and has no default value the application must provide a value during a create operation.
queryable Boolean no Indicates whether or not the property may appear in the WHERE clause of a query statement. Default is true. Only for table properties is false allowed.
defaultValue depending on the
propertyType
no

The value that the system sets for the property if no value is provided when the object is created. If the cardinality is multi there can be more than one default value and a list of all default values is provided.

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

Integer Property Definitions

Attribute Type Required Description
maxValue Integer no The maximum value allowed for this property
minValue Integer no The minimum value allowed for this property.

DateTime Property Definitions

Attribute Type Required Description
- - - -

Decimal Property Definitions

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

Attribute Type Required Description
maxValue Decimal no The maximum value allowed for this property
minValue Decimal no The minimum value allowed for this property.

String Property Definitions

Attribute Type Required Description
maxLength Integer no The maximum length (in characters) allowed for a value of this property.
minLength Integer no The minimum length (in characters) allowed for a value of this property.

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.
An example schema with a table property
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v4.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v4.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.

Attribute Type Required Description
id String yes

The type id of the object type. It uniquely identifies the object type in the schema.

localNamespace URI no By using namespaces, it is possible to form groups of properties and object types.
description String no Describes the property-type.
baseId Enum yes

This indicates the base type of this object type. The following object types are supported:

  • enaio:document
  • enaio:folder
  • enaio:secondary
PropertyReference String no

Reference by id to a property. An object type can have an arbitrary number of property references.

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.


Attribut Type Required Description
contentStreamAllowed Enum yes

This indicates whether objects of this type must, must not, or may have content.

Possible values are:

  • required
  • notallowed
  • allowed (default)
seconaryObjectTypeId String no

References to secondary object types (if there are several secondary object types, they are listed one below the other). Determines which secondary object types an instance of this object type receives when it is created.

In contrast to the CMIS specification, in which the secondary object types can be determined freely on each object instance, the schema specifies which secondary object types an object instance must have.

fileable Boolean no Indicates whether objects of this type can have a parent object. Parent objects must be folders and are referenced in the document by the parentId property.


Folder Object Type Definitions

Folder objects cannot have content. Fileable objects can be assigned to a folder object. Then the folder object is the parent of the fileable objects and the fileable objects are the children of the folder object. The properties of a folder can be marked to be queryableOnChildren. That means, you can use these properties in search queries on child objects. For more details take a look at the search documentation. The attribute queryableOnChildren is an attribute of property references, not of properties. If different folder types reference the same property, queryableOnChildren can have different values in each property reference. The default value of queryableOnChildren is false.

A schema containing folder object types
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v4.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v4.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>enaio:document</baseId>
            <propertyReference>str1</propertyReference>
            <contentStreamAllowed>required</contentStreamAllowed>
	    <fileable>true</fileable>
        </typeDocumentDefinition>
    	<typeFolderDefinition>
    	    <id>folderA</id>
            <baseId>enaio:folder</baseId>
       	    <propertyReference>str1</propertyReference>
            <propertyReference queryableOnChildren="true">str2</propertyReference>
    	</typeFolderDefinition>
    	<typeFolderDefinition>
            <id>folderB</id>
            <baseId>enaio:folder</baseId>
            <propertyReference queryableOnChildren="true">str1</propertyReference>
            <propertyReference queryableOnChildren="false">str2</propertyReference>
            <propertyReference queryableOnChildren="true">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 enaio: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 enaio: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).

A schema containing secondary object types
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v4.0/" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v4.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>enaio:document</baseId>
            <propertyReference>str1</propertyReference>
            <contentStreamAllowed>required</contentStreamAllowed>
            <secondaryObjectTypeId>secondaryA</secondaryObjectTypeId>
        </typeDocumentDefinition>
        <typeSecondaryDefinition>
            <id>secondaryA</id>
            <baseId>enaio:secondary</baseId>
            <propertyReference>str2</propertyReference>
        </typeSecondaryDefinition>
        <typeSecondaryDefinition>
            <id>secondaryB</id>
            <baseId>enaio: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:

Metadata of a document of type documentType1
{
    "objects": [
        {
            "properties": {
                "enaio:objectId": {
                    "value": "7bce6618-2b0e-4abf-af26-e4137e6b0461"
                },
                "enaio:baseTypeId": {
                    "value": "enaio:document"
                },
                "enaio:objectTypeId": {
                    "value": "documentType1"
                },
                "enaio: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. enaio:objectId, enaio:createdBy, enaio:creationDate). The values of system properties are set by the system.