Schema - Defining Object Types

Define properties and reference them in object type definitions for the entire system, for individual tenants or for a specific app.

Table of Contents

Introduction

In yuuvis® Momentum, document and folder objects can be created.

  • Each object has its own metadata including a fixed set of general system properties like system:versionNumber or system:lastModificationDate. Objects with a binary content file assigned to them additionally have a set of content stream properties. Those system properties are predefined.
  • Further metadata properties can be defined in an XML schema file as described below. Those metadata properties can be referenced in object type definitions, usually in the same schema file.

Each object instantiated in yuuvis® Momentum has exactly one of the defined document or folder object types during its entire lifecycle. The properties referenced in the corresponding object type definition are optional or required for the instantiated objects as specified in their definition.

In a schema, it is possible to define secondary object types (SOTs) as well. Those object types cannot be instantiated, but referenced in document or folder object type definitions. The properties of the SOT can be added to the properties of the document or folder object type for the objects that will be instantiated - either during the objects' creation or even during their lifecycle (floating reference).

Tenant-specific (or app-specific) properties and object types should be defined in a tenant (or app) schema, whereas the properties and object types defined in the global schema are available for all tenants and apps.

Schema Outline

A schema contains property definitions and object type definitions in XML format in the following mandatory order. It is possible to skip parts but not to change their order.

  1. Label (as of 2023 Autumn)
  2. Property definitions
  3. Object Type definitions:
    1. Document type definitions
    2. Folder type definitions
    3. Secondary object type definitions

The label is an optional string field to specify a project-specific schema versioning information. Its string value is limited to 128 characters.

A valid example schema
<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>



Scopes and Endpoints for Schemata

In the multi-tenant landscape of yuuvis® Momentum, it is important to be aware of the scope of property and object type definitions.

  • Any object types or properties that should be available for all tenants should to be introduced to the global schema.
  • To prevent cluttering the global schema and allow for duplicate names, app schemata can be used. They provide a namespace for properties and object types pertaining to a particular use case. An app schema is available in all tenants where the app is enabled.
  • Each tenant can have exactly one tenant schema that allows to define properties and object types for usage only within the specific tenant.
    Note: By default, the maximum number of property definitions in a tenant-specific schema is 20. A system integrator can change this limit via the schema.tenant.properties.limit parameter 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.
  • For each tenant, the global schema and the tenant schema are merged with the app schemata for those apps that are enabled for the tenant. The resulting applied tenant schema is used for DMS operations like object import, update or search.

Depending on the schema scope, the schemata are managed via specific endpoints. Furthermore, their property and object type IDs have specific prefixes as described below.

Naming Conventions for Property and Object Type IDs

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

The 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 : character is the prefix. It is useful to specify the scope of the corresponding schema. Within the schema file, all references on the same ID have to be EITHER with OR without prefix. Depending on the situation, the prefix can be omitted, for example to broaden a search query across multiple application schemata.

  • In tenant-specific (app-specific) definitions, only prefixes matching "ten" + <tenant name> ("app" + <app name>) are allowed. The tenant (app) name is case insensitive when used as a path or search parameter. If no prefix is specified, the prefix is added automatically in the applied tenant schema. Thus, the same object type name can occur in multiple tenant (app) schemata.
  • In the global schema all prefixes are allowed, as long as they do not start with ten or app or equal system. Alternatively, they can also have no prefix.

Note: An exception are column names in Table Property Definitions, where prefixes are prohibited as of version 2020 Winter.

As of 2021 Winter, it is possible to use the - character as an additional separator within prefixes for tenant-specific IDs if matching the following regular expression:
([a-zA-Z][a-zA-Z0-9-]*:)?[a-zA-Z][a-zA-Z0-9]*

Property Definitions

General Attributes

All property definitions have the following attributes:

AttributeTypeRequiredDescription
id
StringyesThe ID of the property matching the regular expression. It uniquely identifies the property in the schema.
localNamespace
URInoBy using namespaces, it is possible to form groups of properties and object types.
description
StringnoDescribes the property.
propertyType

EnumyesSpecifies the type of this property. The following types are supported:
  • boolean
  • integer
  • datetime
  • decimal
  • string
  • table
  • id
cardinality
 
Enumyes

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

required
Booleanyes

If true, the object must have at least one value of this property. If a property is required and has no defaultValue, the application must provide a value during the create operation.

This attribute can be overwritten in the property references of object type definitions. Hence, the same property can be required in one object type and not required in another object type.
Following the concept of secondary object types, the same property can be allowed by multiple ways in an object instance, e.g. if the object type has a reference to the property type and the object has one or more secondary object types, that have references to the property type. If these references have different required values, the value true always dominates over false.
Check out the tutorial "Overwriting the 'required' Property Attribute" for further examples.

queryable
 
BooleannoSpecifies whether or not the property may appear in the WHERE clause of a query statement. Default is true. false is only allowed for table properties.
classificationStringno

Declares the classifications this property belongs to. There is no validation or use in the system itself. For example, string properties can be classified as email or url and a client application can use this classification to present the property's content in an appropriate manner. This attribute can be used several times and the corresponding values are delivered in an array.

Note: Make sure to validate the strings you set for the classification attribute, such that your client application will not fail if a string does not match the expected syntax.

defaultValue
depending on the
propertyType
no

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

Default values can be also applied by update. Assume a secondary object type has property types with default values. If you add this secondary object type to an existing object by update, these default values are applied, if the update does npt set values for these properties and the properties were not allowed in the object before the update.

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

Attributes for Integer Property Definitions

AttributeTypeRequiredDescriptionTechnical Limit used as Default
maxValue
IntegernoThe maximum value allowed for this property9223372036854775807
minValue
IntegernoThe minimum value allowed for this property.-9223372036854775808

Attributes for DateTime Property Definitions

AttributeTypeRequiredDescription
resolution
EnumnoThe only supported value is date. If the resolution is set to date, the property can only store values without a time part and these values have the format yyyy-MM-dd.

Attributes for Decimal Property Definitions

Decimal properties support values of 64-bit precision (IEEE 754). The values have to be specified in decimal notation. However in the table below, the technical limits are provided in base 2 scientific notation in order to display the values in a condensed and comfortable format. This format cannot be used to specify the value for a maxValue or minValue attribute in a decimal property definition.

AttributeTypeRequiredDescriptionTechnical Limit used as Default
maxValue
DecimalnoThe maximum value allowed for this property(2-2 -52 )·2 1023 
minValue
Decimalno The minimum value allowed for this property. -(2-2 -52 )·2 1023 

Please note the additional limit of precision: values of magnitude smaller than 2 -1074 will be rounded to 0. 

Attributes for String Property Definitions

AttributeTypeRequiredDescription
maxLength
IntegernoThe maximum length (in characters) allowed for a value of this property.
minLength
Integerno

The minimum length (in characters) allowed for a value of this property.

fulltextIndexed
Booleanno

If true (default), the property value can be found via full-text search.
If false, the property value cannot be found via full-text search.
>> Search with CONTAINS statement

In general, the length of a string is limited to 8192. Hence, the maximum value for maxLength and minLength is 8192.

Attributes for Table Property Definitions

Table

A table property definition contains a list of one or more sub-property definitions, the columns.

The cardinality of a table 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 a table (query keyword CONTAINS). If queryable is true, you can apply more precise search queries to a 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.

Columns

Each column can have a different property type and has its own attributes, such as required, defaultValue or cardinality (single or multi). The values are applied to each row entry.

As of version 2020 Winter, the column names specified via <id>examplecolumn</id> must not contain a prefix. They have to follow the convention [a-zA-Z][a-zA-Z0-9]*. Otherwise, the schema containing the corresponding property definition will not pass the validation.

Example

An example schema with a table property
<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>

Structured Data Property Definition

As of version 2021 Summer, yuuvis® Momentum offers a property type for the storage of structured data in JSON format. Thus, it is possible to store interleaved data structures in a queryable way without defining each single sub-property in the schema. An example definition is shown in the code block below. The schema validation checks if the ID follows the convention. Only the value single is allowed as cardinality .

Note: The structured data properties should NOT be considered to replace the concept of a well-defined schema. They should be used only if the handling of objects' metadata via the conventional property definitions is not reasonable.

Example Structured Data Property Definition
    <propertyStructuredDataDefinition>
        <id>customerdetails</id>
        <propertyType>structureddata</propertyType>
        <cardinality>single</cardinality>
        <required>false</required>
    </propertyStructuredDataDefinition>

Even if the schema allows various structured data properties in an object, the instantiated object can contain a value for at most one structured data property.

There are strict rules for the values that can be specified for structured data properties assigned to an object. Find all details in the linked chapter.
>> Structured Data in Request Bodies

Structured data properties are queryable similar to table properties.
>> Queries on Structured Data

This example tutorial provides explanations and code examples to get an idea on how to define and specify structured data properties and on how to query them.
>> Setting and Querying Structured Data

Object Type Definitions

There are different groups of object type definitions:

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

All object type definitions have the following attributes:

AttributeTypeRequiredDescription
id
Stringyes

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

localNamespace
URInoBy using namespaces, it is possible to form groups of properties and object types.
description
StringnoDescribes the property definition.
baseId
Enumyes

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

  • system:document
  • system:folder
  • system:secondary
propertyReference 

Stringno

Reference by ID to a property. An object type definition 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 objects' type must be a document type.

Note

As of 2023 Spring, the predefined object type system:document can be used as object type. It automatically has a floating reference on all SOTs that are available in the applied tenant schema as described below. 

Custom document object type definitions have the following specific attributes:

AttributTypeRequiredDescription
contentStreamAllowed
Enumyes

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

Possible values are:

  • required
  • notallowed
  • allowed (default)

Note

The attribute is also available for secondary object type definitions. If a secondary object type with a specified contentStreamAllowed attribute is referenced in the document object type definition, it might influence the final value of contentStreamAllowed or even lead to contradictions. Conflict situations can occur and lead to an invalid schema or invalid documents. The schema is invalid if the conflict occurs between secondary object type definitions and document object type definitions. Conflict situations between referenced secondary object types are not detected in the schema validation process, but can also lead to invalid documents. Find more details in the section on secondary object type definitions.

secondaryObjectTypeId
Stringno

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 upon creation (static="true") or can be added at runtime (static="false").
>> Secondary Object Type Definitions

Note: If you use the predefined system:document document object type instead of defining your own, all available SOTs will automatically be referenced with (static="false") internally.

In contrast to the CMIS specification (Content Management Interoperability Services), in which the secondary object types can be determined freely for each object instance, the schema specifies which secondary object types an object instance must have.

Folder Object Type Definitions

Folder objects do not have their own content files in contrast to document objects. In yuuvis® Momentum versions 2020 Autumn and older, folders cannot be set up in a hierarchical structure  a folder inside a folder is not allowed. As of version 2020 Winter, a folder hierarchy is possible. Folders allow the grouping of multiple objects and have their own metadata which will not be inherited by the assigned objects. They act as object parent being referred to by its system:objectId property value in the individual metadata of the child objects as system:parentId and thus are also taken into account during the search. Similar to a document object type a folder can reference a secondary object type's property group. The properties can be used as regular properties on folder level. Folders with objects assigned to them cannot be deleted.

The following code block shows the example folder object type definition "dossier" that can be integrated into any given schema. Note that folder object type definitions need to be defined after all document type definitions, yet before any secondary object type definitions.

Schema containing a folder object type
<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>
      
        <typeDocumentDefinition>
            <id>documentType1</id>
            <baseId>system:document</baseId>
            <propertyReference>str1</propertyReference>
            <contentStreamAllowed>required</contentStreamAllowed>
            <secondaryObjectTypeId>secondaryA</secondaryObjectTypeId>
        </typeDocumentDefinition>
       
		<typeFolderDefinition>
        	<id>dossier</id>
       		<baseId>system:folder</baseId>
        	<propertyReference>title</propertyReference>
        	<propertyReference>type</propertyReference>
        	<propertyReference>description</propertyReference>
    	</typeFolderDefinition>
</schema>

During import or update of a document object the object ID of the target folder is provided as the new object's parent ID (system:parentId). Actions such as assigning objects, moving them to or removing them from a folder can easily be carried out in this way. A validation takes place and checks whether the given ID is a folder and does exist. Furthermore, as of version 2020 Winter, folders in a folder will be allowed. The folder hierarchy will represent a tree structure where each folder cannot appear as a parent in different levels of the structure. Hierarchies that do not adher to this structure will not pass validation.

After schema modification, a folder object can be created by importing the following metadata:

Metadata for a folder object according to schema above
{
	"objects": [
	{
		"properties": {
			"system:objectTypeId": {
				"value": "dossier"
			},
			"title": {
				"value": "My E-mail Folder #1"
			},
			"type": {
				"value": "E-mails"
			},
			"description": {
				"value": "This folder holds all the e-mails authored by me"
			}
		}
	}
	]
}

After extracting the object ID of the folder from the import response, you can start populating the folder with documents:

Metadata of a document destined for the folder
{
	"objects": [
	{
		"properties": {
			"system:objectTypeId": {
				"value": "documentType1"
			},
			"system:parentId": {
				"value": "<the Folder object ID from the import response"
			},
			"str1": {
				"value": "Some important business documents"
			},
			"description": {
				"value": "This folder holds all the e-mails authored by me"
			}
		}
	}
	]
}

Folder object type definitions have the following specific attributes:

AttributeTypeRequiredDescription
secondaryObjectTypeId
Stringno

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 upon creation (static="true") or can be added at runtime (static="false").
>> Secondary Object Type Definition

In contrast to the CMIS specification (Content Management Interoperability Services), in which the secondary object types can be determined freely for each object instance, the schema specifies which secondary object types an object instance must have.

Secondary Object Type Definitions

Secondary object types are abstract. This means that they cannot be instantiated. They 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 object types (e.g., documents or folders). Like other object types, a secondary object type can have references to properties. They can also have no properties at all which can be understood as a way of categorizing document types (tagging). Document or folder object types can in turn reference secondary object types, which give them their properties. There are two ways for secondary object types to be referenced by an object in the schema definition: as static or as floating.

  • <secondaryObjectTypeId static="true">INV</secondaryObjectTypeId>.
  • <secondaryObjectTypeId static="false">INV</secondaryObjectTypeId>.

As of 2023 Spring, the predefined object type system:document automatically has a floating reference on all SOTs that are available in the applied tenant schema. Nevertheless, the rules for the contentStreamAllowed attribute for the the individual SOTs have to be considered before they are assigned to an object.

The property groups of static referenced secondary object types are automatically available in all instances of the object type. Floating secondary object types can be handled in a flexible way during the import (POST /api/dms/objects endpoint) or at runtime for already existing instances of an object type with an update (POST /api/dms/objects/{objectId} / PATCH /api/dms/objects/{objectId}).  The keywords "add":, "value": or "remove": can be used in the "system:secondaryObjecttypeIds": property area of the metadata.json filecan.

Keyword

TypeDescriptionmetadata.json
"value":
array, comma-separated list

during import or update

adds one or multiple secondary object types to an object

Note that the list of "floating" secondary object types transferred will replace all existing ones. This includes the related properties and their metadata values. If you want to keep an existing "floating" secondary object type, you have to list it as well.

{
    "objects": [{
        "properties": {
            "system:objectTypeId": {
                "value": "appSot:document"
            }
            "system:secondaryObjectTypeIds": {
                "value": ["INV","SUP"]
            }
...
"add":
string

during update

adds a single secondary object type to an object

{
    "objects": [{
        "properties": {
            "system:secondaryObjecttypeIds": {
                "add": "INV"
            },
...
"remove":
string

during update

removes a single secondary object type from an object

Note: The metadata assigned to the object by referencing the secondary object type will be deleted for the current object version!

{
    "objects": [{
        "properties": {
            "system:secondaryObjecttypeIds": {
                "remove": "INV"
            },
...

Document object types have a system:secondaryObjectTypeIds property 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 searchThe secondary object type must be explicitly specified in the FROM clause: select * from appSot:INV.

The system:secondaryObjectTypeIds property is set by the repository using the schema.

Schema containing secondary object types
<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>appSot:dateOfReceipt</id>
            <propertyType>date</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>appSot:comment</id>
            <propertyType>date</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>appSot:invoiceNo</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
        <propertyStringDefinition>
            <id>appSot:paymentTerm</id>
            <propertyType>string</propertyType>
            <cardinality>single</cardinality>
            <required>true</required>
        </propertyStringDefinition>
         
        <typeDocumentDefinition>
            <id>appSot:document</id>
            <baseId>system:document</baseId>
            <propertyReference>appSot:dateOfReceipt</propertyReference>
            <contentStreamAllowed>required</contentStreamAllowed>
            <secondaryObjectTypeId>appSot:basicInfo</secondaryObjectTypeId>
        </typeDocumentDefinition>
         
        <typeSecondaryDefinition>
            <id>appSot:basicInfo</id>
            <baseId>system:secondary</baseId>
            <propertyReference>appSot:comment</propertyReference>
        </typeSecondaryDefinition>
        <typeSecondaryDefinition>
            <id>appSot:invoice</id>
            <baseId>system:secondary</baseId>
            <propertyReference>appSot:invoiceNo</propertyReference>
            <propertyReference>appSot:paymentTerm</propertyReference>
        </typeSecondaryDefinition>
</schema>

Consider the example schema. If a document of the type appSot:document is created, it may have values for the properties appSot:dateOfReceipt and appSot:comment. For the appSot:dateOfReceipt property definition this is obvious, because there is a direct reference in the document type definition of appSot:document

The appSot:comment property definition is not directly referenced but the definition of appSot:document has a reference to the secondary object type appSot:basicInfo which references the appSot:comment property definition. Thus, both properties are available for creating documents.

Furthermore, properties passed on by secondary object types are treated like "regular" properties in a document. The attributes of a property are taken into account. For example, a document of the type appSot:document not only may have a value for appSot:comment, it must have a value, because it is a required property. It makes no difference, whether a document type references the property definitions directly or indirectly via a secondary object type reference.

You cannot tell from the metadata of a document any longer 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 based on the appSot:document document type definition may look like this:

Metadata of appSot:document
{
    "objects": [
        {
            "properties": {
                "system:objectId": {
                    "value": "7bce6618-2b0e-4abf-af26-e4137e6b0461"
                },
                "system:baseTypeId": {
                    "value": "system:document"
                },
                "system:objectTypeId": {
                    "value": "appSot:document"
                },
                "system:secondaryObjectTypeIds": {
                    "value": [
                        " appSot:basicInfo"
                    ]
                },
                <...>
                " appSot:dateOfReceipt": {
                    "value": "2020-02-20T02:02:20.220Z"
                },
                "appSot:comment": {
                    "value": "Yearly invoice - payment 1 out of 12 monthly payments."
                }
            },
            "contentStreams": [
                <...>
            ]
        }
    ]
}

Secondary object type definitions have the following attributes:

Attribute

TypeRequiredDescription

contentStreamAllowed
(As of product version 2020 Autumn)

Enumno

Can substantiate the contentStreamAllowed attribute of document type definitions. Possible values are analogous to document object type definitions: required, notallowedallowed.

For the final document, content will be allowed if only allowed values occur in the document type definition and included secondary object type definitions for this attribute.

For the final document, content will be required (notallowed) if the value is required (notallowed) in at least one object type definition  either document type definition or included secondary object type definition.

Conflict situation leading to invalid documents: any combination of at least once required and at least once notallowed in included secondary object type definitions or the document object type definition itself.

  • If the conflict occurs between the document object type definition and a secondary object type definition, the whole schema is invalid.
  • If the conflict occurs between secondary object type definitions with at least one of them referenced as static, the schema is valid but the document validation will fail (instantiated documents will be invalid).
  • If the conflict occurs exclusively between secondary object type definitions referenced as floating, a document cannot have conflicting secondary object types at the same time. If a secondary object type with the value required (notallowed) is added to the document, all secondary object types with the value notallowed (required) must be removed by means of the keyword "remove":.

If contentStreamAllowed is specified in a secondary object type definition, this secondary object type cannot be referenced in folder object type definitions. The schema would be invalid.

Validation

It is not possible to post an invalid schema via yuuvis® Momentum API. A new schema is always validated before it is introduced into the system. Additionally, specific validation endpoints are available to check the new schema before sending an update request.
>> Schema Management Endpoints

The response of schema validation (or update) endpoints are always structured as shown in the following example.

Schema Validation Example Response
{
    "validationErrors": [],
    "changes": [{
            "type": 1000,
            "message": "Document type was removed.",
            "id": "appEmail:obsoleteType",
            "affectedObjects": {
                "tenant1": 10,
                "tenant2": 4
            }
        }, {
            "type": 1200,
            "message": "A property reference was removed from a document type.",
            "id": "appEmail:email",
            "reference": "appEmail:bcc",
            "affectedObjects": {
                "tenant1": 1,
                "tenant2": 3
            }
        }
    ]
} 

Failed Validation

If the schema is invalid, the corresponding validation errors are listed in validationErrors as described here:
>> Error Lists during Validation Processes

Passed Validation

If the schema is valid, the validationErrors list is empty. The schema can be (is) updated.

However, the new schema might define different structures for DMS objects that are not matched by previously imported objects. Thus, affected objects are invalidated as soon as the new schema is introduced into the system. Invalidated objects are still stored in the system, but their availability and behavior deviates from expectation as described in the following table and below.

The changes list in the validation request contains all detected differences between the new schema and the previously used schema that could lead to invalidation of existing DMS objects. The following table documents the detectable types of schema changes and their individual values/meanings of the sub-parameters for each element in the changes list:

  • type
  • message
  • id
  • reference
  • if the validation (or update) endpoint is called with the query parameter verbose=trueaffectedObjects

Note

A non-empty changes list in the validation request does NOT prevent a schema update.


typemessageidreferenceDescription and Impact of Schema Update
1000Document type was removed.ID of the removed document type-As it is not possible to replace the object type of existing objects, it is not possible to adjust affected objects. They cannot be updated anymore.
1001Folder type was removed.ID of the removed folder type-See impacts of change type 1000.
1100A secondary object type reference was removed from a document type.ID of the document typeID of the secondary object typeIf the corresponding SOT includes required properties, see the impacts of change type 1200.
1101A secondary object type reference was removed from a folder type.ID of the folder typeID of the secondary object typeIf the corresponding SOT includes required properties, see the impacts of change type 1200.
1110A document type got a new static secondary object type reference.ID of the document typeID of the secondary object type

A static secondary object type reference was added to a document type definition. Or an existing non-static secondary object type reference on a document type definition became static.

If the corresponding SOT includes required properties, see the impacts of change type 1300.

1111A folder type got a new static secondary object type reference.ID of the folder typeID of the secondary object type

A static secondary object type reference was added to a folder type definition. Or an existing non-static secondary object type reference on a folder type definition became static.

If the corresponding SOT includes required properties, see the impacts of change type 1300.

1200A property reference was removed from a document type.ID of the document typeID of the property

Any metadata retrieval of affected objects excludes the removed property. Search result lists, e.g., are affected as well. However, the existing values remain in the database and the search index. Thus, in case of a removed string property, the existing values are still considered for full-text search.

The corresponding values are removed automatically during the next PATCH or POST update on the affected objects.

1201A property reference was removed from a folder type.ID of the folder typeID of the property

See impacts of change type 1200.

1210A property reference was removed from a secondary object type.ID of the secondary object typeID of the property

See impacts of change type 1200.

1300A non-required property type became required.ID of the property-POST metadata updates on affected objects are only allowed if the new required property is properly added.
1310A required property reference was added to a document type, or a non-required property reference became required.ID of the document typeID of the propertySee impacts of change type 1300.
1311A required property reference was added to a folder type, or a non-required property reference became required.ID of the folder typeID of the propertySee impacts of change type 1300.
1320A required property reference was added to a secondary object type, or a non-required property reference became required.ID of the secondary object typeID of the propertySee impacts of change type 1300.
2000Content stream becomes required on a document type.ID of the document type-Updates on affected objects are only allowed if a binary content file is thereby added.
2001Content stream becomes not allowed on a document type.ID of the document type-Updates on affected objects are only allowed if a binary content file is thereby deleted. Thus, affected objects with a binary content file under retention cannot be updated via yuuvis® Momentum at all.
2010Content stream becomes required on a secondary object type.ID of the secondary object type-See impacts of change type 2000.
2011Content stream becomes not allowed on a secondary object type.ID of the secondary object type-See impacts of change type 2001.
3000The cardinality of a property becomes 'single'.ID of the property-Updates on affected objects are only allowed if the value of the modified property is properly replaced. Especially, pure tag and content operations are only allowed after a proper update of the metadata.

Following schema changes are NOT detected during the validation, but can affect existing objects as well:

  • The type of a property definition changed. → See impacts of change type 3000.
  • The range of a property definition changed. → See impacts of change type 3000.
  • A default value was added to a property definition or reference. → The new default value is only used for the creation of new objects.
  • In a table property definition, the value for the queryable attribute was changed. → Affected objects can be adjusted via COMMANDER service.
  • The base type of an object type changed from system:folder to system:document with content stream required. → See impacts of change type 2000.
  • The base type of an object type changed from system:document to system:folder. → See impacts of change type 2001.
  • The base type of an object type changed from system:document or system:folder to system:secondary. → See impacts of change type 1000.

System Properties

General Object Properties

In addition to the properties assigned to the object types in the schema, each instantiated object has a set of general system properties. Some system properties are set by the system and some system properties can be set by the user.

PropertyTypeDescriptionSet by
system:objectIdstringIdentifies the object in the database.system
system:baseTypeIdstringIdentifies the object type the object instantiates. Secondary object types are not allowed.system
system:objectTypeId

string

Required during an import and cannot be changed lateron.

Identifies the object's type.

user

system:secondaryObjectTypeIds

JSON list of stringsContains the secondaryObjectTypeId for each secondary object type associated with the document object type in the schema.user
system:createdBystringuserId of the user that has initially created the object.system
system:creationDatestringDate of the object's creation in format yyyy-MM-ddTHH:mm:ss.fffZ.system
system:lastModifiedBystringuserId of the user that sent the last successful POST request on the object.system
system:lastModificationDatestringDate of the last successful POST request on the object as a string in format yyyy-MM-ddTHH:mm:ss.fffZ.system

system:parentId

string

system:objectId of the parent folder. Available for documents and as of version 2020 Winter, also for folders.

During an import or update operation, the object can be assigned to an existing folder by referencing its system:objectId in the system:parentId of the target document or folder object. The existence of the parent folder is validated by means of the specified system:parentId. Furthermore, circles in the folder hierarchy are forbidden and do not pass the validation.

user
system:parentObjectTypeId

string

Identifies the folder object type of the parent folder that is specified by system:parentId.

Available for document object types and as of version 2020 Winter, also for folder object types.

system
system:versionNumberintegerInteger object version number. Corresponds to the number of POST requests on the object starting with the initial creation.system
system:tenantstringIdentifies the tenant the object belongs to.system
system:traceIdHexadecimal lowercase string with maximum length 16The traceid of the import operation or last update operation.

Unique process number of any operation. If not specified in the request, a random string value will be set.

system

system:tags

JSON table of strings and integers

Contains the properties of the tags assigned to the object.

>> Tagging

user

system:rmExpirationDate

string

Only available for documents. Secondary object type system:rmDestructionRetention is required.

The binary content of the object cannot be changed or deleted before this date, but metadata updates are allowed. In an update request, the system:rmExpirationDate cannot be replaced by an earlier date.

>> Document Retention

user

system:rmStartOfRetention

string

Only available for documents. Secondary object type system:rmDestructionRetention and a non-null value for system:rmDestructionRetention is required.

This date defines the start of the retention time. It has to be earlier in time than the system:rmExpirationDate.

user

system:rmDestructionDate

string

Only available for documents. Secondary object type system:rmDestructionRetention and a non-null value for system:rmDestructionRetention is required.

If system:rmDestructionRetention is set, it must either be equal to or later in time than system:rmExpirationDate.

user

Content Stream Properties

The contentStreams group of properties comprises system properties of document objects containing binary content. Thus, their contentStreamAllowed attribute has to be required or allowed. The properties in contentStreams contain all information necessary to be able to handle binary content. Depending on the type of operation, different properties are required for import/update requests or are displayed in a response.

PropertyTypeDescriptionIn an Import/Update RequestIn a Response
contentStreamIdString

Points to existing content within a repository.

Required only for pointing to existing content during an import. If not specified, the system generates a UID.

displayed
lengthIntegerLength of the binary content, determined by the system.-displayed (if system could determine the value)
mimeTypeString

Mime type of the content file.

The CONTENTANALYZER service can be configured to determine (scenario A) or not determine (scenario B) the mimeType.
>> serviceConfiguration.json

If mimeType can/should not be determined and is not specified, the default value application/octet-stream is used.

Scenario A:

The CONTENTANALYZER determines mimeType from the corresponding binary content file. It is not possible to set a value via a request header.

In an import request, the automatically determined mimeType can be overwritten by specifying a value in the import JSON.

Scenario B:

In an import request via POST /api/dms/objects, mimeType is determined based on the Content-Type header that is specified for the request's part related to the corresponding binary content file. If mimeType is specified in the import JSON, this value is used instead of the automatically determined one. 

In a content update via POST /api/dms/objects/{objectId}/contents/file, mimeType is determined based on the Content-Type header specified for the entire HTTP request.

displayed
fileNameString

Name of the content file.

If fileName is not specified as follows and cannot be determined, the default value upload.bin will be set.

In a content update via POST /api/dms/objects/{objectId}/contents/file, fileName is determined based on the Content-Disposition header that is specified for the entire HTTP request.

In an import request via POST /api/dms/objects, fileName is determined based on the Content-Disposition header that is specified for the request's part related to the corresponding binary content file. If fileName is specified in the import JSON, this value is used instead of the automatically determined one.

displayed
digestStringSHA-256, automatically determined by REPOSITORY Service based on the binary content. Can be used to detect changes in the binary content.
>> GET /api/dms/objects/{objectId}/actions/validate/digest
-displayed
repositoryIdString

ID of the repository that will be used for storage of the binary data.

Required only for pointing to existing content during an import. If not specified, the default repository defined in the repository service configuration will be set.displayed
archivePathString

Path structure for the content file within the binary storage.

Required only for pointing to existing content during an import if reconstruction is not possible with metadata information (e.g,, if a pathTemplate containing dynamic path elements like DATE is configured in the archive profile).

displayed if it was set

rangeString

Applies to compound documents only. Defines a certain segment of compound documents that should be provided for content retrievals.


Optional in the import request body and only available for compound documents.displayed only if it was set
cidStringAssigns the corresponding multipart content.Required in the import request body. Not needed later on and therefore not stored in the system.-


Read on

Managing the Schema 

This tutorial shows how to use the Core API to get the tenant-specific schema of the system, how to validate a schema, and how to bring in a new schema. Keep reading

Importing Documents 

This tutorial shows how documents can be imported into a yuuvis® API system via the Core API. During this tutorial, a short Java application will be developed that implements the HTTP requests for importing documents. We additionally provide a JavaScript version of this tutorial.  Keep reading

Changing Schema Structures

This tutorial shows how to change your basic schema for individual instances of an object type during the entire lifecycle of a document. Classify objects at a later point in time, add or remove property groups at runtime by defining and referencing "floating" secondary object types. Keep reading