This tutorial shows how to reference the same property definition in different object type definitions, in some of them as a required property and in others as a non-required property.

Table of Contents

Introduction

The metadata structure of object types has to be defined in the schema. In this definition, properties are referenced that should be connected to the object type. Each property is in turn defined in the schema by the specification of its attributes. The properties can be referenced or not referenced in object type definitions, but their attributes are fixed and cannot be modified. The required attribute is the only exception as it can be overwritten by a propertyReference in object type definitions. This makes it possible to decide for each property individually whether it is required in every single object type definition or not. Since schema structures can even be changed at runtime, yuuvis® Momentum offers a high flexibility in terms of document lifecycle management.

Requirements

To work through this tutorial, the following is required:

Set-up yuuvis® Momentum system (see Installation Guide)
A user with read and write permissions on a document type in the system (see tutorial for permissions)

Overwriting the `required` Attribute of Properties

All property definitions in the schema need the specification of the required attribute. Its boolean value decides if the corresponding property is mandatory (true) or optional (false) for an object. However, the value of the required attribute can be overwritten by a propertyReference in object type definitions.

Property Definition

In an import management system, documents may be imported with less properties than they will have lateron in their lifecycle. A freshly imported object for example does not necessarily have an editor. Later in the document lifecycle, this information may be required. By overwriting the required attribute of the editor property, it is possible to use the same property throughout the entire lifecycle.

In the example code below, the editor property is defined. The required attribute of the editor property is set to true. If not overwritten by a propertyReference, the editor property will be mandatory for any object of a type containing the editor property in its definition.

Property definition

<propertyStringDefinition>
    <id>editor</id>
    <propertyType>string</propertyType>
    <cardinality>single</cardinality>
    <required>true</required>
</propertyStringDefinition>

Overwriting Using a Document Type Definition

In a document type definition, a propertyReference can be used to set a value for the required attribute of a property. This value can be different from the value specified in the property definition. In this case, the value of the required attribute will be specified in the document type definition.

Since the editor property should be optional for an imported1 document, the required attribute is set to false by means of a propertyReference.

Overwriting of the required attribute by document type definition

<propertyStringDefinition>
    <id>editor</id>
    <propertyType>string</propertyType>
    <cardinality>single</cardinality>
    <required>true</required>
</propertyStringDefinition>

<typeDocumentDefinition>
    <id>imported1</id>
    <baseId>system:document</baseId>
    <propertyReference required="false">editor</propertyReference>
    <contentStreamAllowed>allowed</contentStreamAllowed>
</typeDocumentDefinition>

Overwriting Using a Secondary Object Type Definition

An alternative option to reference a property in an object type definition is to include a floating secondary object type. In the secondary object type definition, a propertyReference can be used to set a value for the required attribute for a property. The required attribute value specified in the original property definition is again overwritten.

In the example code below, the editor property is not included directly in the imported2 document type definition. But it is based on the non-static (floating) secondary object type noeditor. The definition of noeditor uses the editor property and sets its required attribute to false by means of a propertyReference. Thus, for documents of the type imported2, the editor property will be available and optional.

Overwriting of the required attribute by secondary object type definition

<propertyStringDefinition>
    <id>editor</id>
    <propertyType>string</propertyType>
    <cardinality>single</cardinality>
    <required>true</required>
</propertyStringDefinition>

<typeDocumentDefinition>
    <id>imported2</id>
    <baseId>system:document</baseId>
    <contentStreamAllowed>allowed</contentStreamAllowed>
    <secondaryObjectTypeId static="false">noeditor</secondaryObjectTypeId>
</typeDocumentDefinition>
 
<typeSecondaryDefinition>
    <id>noeditor</id>
    <baseId>system:secondary</baseId>
    <propertyReference required="false">editor</propertyReference>
</typeSecondaryDefinition>

Handling Multiple Property References

In a document type definition, it is possible to set a value for the required attribute of a property, and additionally include multiple secondary object types specifying the required attribute for the same property as well. If at least one definition implies required=true, this attribute will be true for every document of the corresponding type. The value true dominates over false regardless of the location of the propertyReference.

In the example code below, a document type imported3 is defined. The editor property is included, but the required attribute is overwritten to false which makes the editor property optional. However, the two secondary object types noeditor and witheditor may have different values specified for the required attribute of the editor property.

Document type definition and secondary object type definitions

<propertyStringDefinition>
    <id>editor</id>
    <propertyType>string</propertyType>
    <cardinality>single</cardinality>
    <required>true</required>
</propertyStringDefinition>

<typeDocumentDefinition>
    <id>imported3</id>
    <baseId>system:document</baseId>
    <propertyReference required="false">editor</propertyReference>
    <contentStreamAllowed>allowed</contentStreamAllowed>
    <secondaryObjectTypeId static="false">noeditor</secondaryObjectTypeId>
    <secondaryObjectTypeId static="false">witheditor</secondaryObjectTypeId>
</typeDocumentDefinition>

<typeSecondaryDefinition>
    <id>noeditor</id>
    <baseId>system:secondary</baseId>
    <propertyReference required="false">editor</propertyReference>
</typeSecondaryDefinition>
 
<typeSecondaryDefinition>
    <id>witheditor</id>
    <baseId>system:secondary</baseId>
    <propertyReference>editor</propertyReference>
</typeSecondaryDefinition>

The definition of the secondary object type noeditor overwrites the required attribute of the editor property to false. This value equals the specification in the imported3 document type definition. In contrast, the definition of witheditor includes the editor property by means of a propertyReference but does not explicitly specify a value for the required attribute. This means that the value true from the property definition will be used for witheditor.

If a document of type imported3 has none of the two secondary object types, the editor property is optional.
If a document of type imported3 has the secondary object type noeditor, nothing changes. The editor property is still optional.
But if a document of type imported3 has the secondary object type witheditor, the property editor is mandatory in this object.

Summary

This tutorial gave an introduction into the possibilities provided by the option of overwriting the required attribute of properties. Since this topic plays a role in the handling of the schema, also the following pages might be interesting to you.

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

Schema - Defining Object Types

Detailing the available schema, object type definitions as well as property definitions. Keep reading

DMS Endpoints

To update the instance of an object type with the property group of a floating secondary object type as well as specific values use one of the two endpoints for updating metadata. Keep reading

Browser not supported