Custom Properties

This implementation guideline gives more details and examples on the usage and the correct interpretation of the VEC concept: Extensibility with Custom Properties.

CustomProperty is available in all subclasses of ExtendableElement. In the following examples the class Person is used, which intentionally is not a subclass of ExtendableElement, but for a clear and easy to understand example of custom properties it is well suited.

The left side shows the Person class as defined in the VEC. The right hand side shows an excerpt from the domain of an arbitrary Tool. As you can see in the UML model, the class on the right side contains the attributes employeeNumber and different usages of the class Address, which are both not represented in the VEC. Despite the lack of explicit modelling concepts with this specific semantic, the extension mechanisms of the VEC still allow the exchange of this information within the VEC. The VEC supports extensions of the following type:

• Additional properties (attributes), either single or multi-valued (All subclasses of CustomProperty, e.g. SimpleValueProperty or BooleanValueProperty).
• Contained structures, either single or multi-valued (the ComplexProperty, e.g. simple objects like the address).

These concepts do not support the extension of elements with additional relationships (IDREF in XML).

XML Examples / Snippets

The following XML snippets illustrate the correct usage of the concepts to support the business model shown in the UML diagram above.

Simple Property

The snippet shows the extension of a Person object by the property EmployeeNumber (String). The VEC supports a wide range of primitive property types (e.g. Boolean, Date, Numerical, see the subclasses of CustomProperty for a complete list), so keep in mind to choose the correct type for the corresponding value.

<vec:VecContent ...>
    [...]
    <Person id = "id_01">
      <CustomProperty id="id_01_1" xsi:type="vec:SimpleValueProperty">
          <PropertyType>EmployeeNumber</PropertyType>
          <Value>ABC123</Value>
      </CustomProperty>
      <Department>IT</department>
      <FirstName>John</firstName>
      <LastName>Doe</lastName>
    </Person>
    [...]
</vec:VecContent>

Complex Property

If a VEC object is to be extended by an attribute of a structured data type, the approach is analogous to the simple property. Only a ComplexProperty is used instead. The PropertyType defines the role of the structured data in the context of the parent object (in other words the “attribute name”, e.g. HomeAddress). The individual attributes of the structured data type in turn are then mapped as simple properties within the ComplexProperty. For deeper structured data it is perfectly valid to define ComplexPropertys that contain ComplexPropertys again.

If the same data structure (not the same data) should appear in different roles (e.g. HomeAddress, WorkAddress) another ComplexProperty with a different PropertyType is defined. A concept for sharing / reusing the data defined in such structures is not part of the VEC extension concepts.

<vec:VecContent ...>
    [...]
    <Person id = "id_01">
        <CustomProperty id="id_01_1" xsi:type="vec:ComplexProperty">
            <PropertyType>HomeAddress</PropertyType>
            <CustomProperty id ="id_01_1_1" xsi:type="vec:SimpleValueProperty">
                <PropertyType>Street</PropertyType>
                <Value>Central Street 1</Value>
            </CustomProperty>
            <CustomProperty id ="id_01_1_2" xsi:type="vec:SimpleValueProperty">
                <PropertyType>City</PropertyType>
                <Value>Anytown</Value>
            </CustomProperty>
            <CustomProperty id ="id_01_1_3" xsi:type="vec:IntegerValueProperty">
                <PropertyType>PostalCode</PropertyType>
                <Value>04325</Value>
            </CustomProperty>
        </CustomProperty>
        <CustomProperty id="id_01_2" xsi:type="vec:ComplexProperty">
            <PropertyType>WorkAddress</PropertyType>
            [...]
        </CustomProperty>
        [...]
    </Person>
    [...]
</vec:VecContent>

Multi-Valued Custom Properties

If an object shall be extended by a multi-valued property (e.g. AdditionalAddresses) multiple custom properties (either simple or complex) with the same PropertyType are defined.

<vec:VecContent ...>
    [...]
    <Person id = "id_01">
        <CustomProperty id="id_01_1" xsi:type="vec:ComplexProperty">
            <PropertyType>AdditionalAddresses</PropertyType>
            <CustomProperty id ="id_01_1_1" xsi:type="vec:SimpleValueProperty">
                <PropertyType>Street</PropertyType>
                <Value>Central Street 1</Value>
            </CustomProperty>
            <CustomProperty id ="id_01_1_2" xsi:type="vec:SimpleValueProperty">
                <PropertyType>City</PropertyType>
                <Value>Anytown</Value>
            </CustomProperty>
            <CustomProperty id ="id_01_1_3" xsi:type="vec:IntegerValueProperty">
                <PropertyType>PostalCode</PropertyType>
                <Value>04325</Value>
            </CustomProperty>
        </CustomProperty>
        <CustomProperty id="id_01_4" xsi:type="vec:ComplexProperty">
            <PropertyType>AdditionalAddresses</PropertyType>
            [...]
        </CustomProperty>
        [...]
    </Person>
    [...]
</vec:VecContent>