T1: Implement "Status-based filtering" feature

[rousso]

The conceptual model contains elements that are not ready for inclusion in the semantic data specification or that reference elements defined in other ontologies. The objective of this task is to implement a mechanism that lets the user select what elements will be included in the transformation.

The mechanism should be controllable through configuration files where the user can list inclusion rules for the transformation. The user should also be able to define the target artifact of each inclusion rule so that it can be applied to specific OWL or SHACL artefacts.

The following configuration options are required:

• No source selection specified: The default behaviour is to export all elements in the model.
• Specified Statuses: The configuration should also support filtering out by status. For example, specifying ['Draft'] will filter out elements with a 'Draft' status from the export. See: model2owl#202

The implementor is expected to:

• Provide a draft configuration format: The contractor will define and propose a user-friendly configuration format that supports simple and advanced filtering scenarios, such as multiple outputs and sources, as well as being compatible with the export of restriction on controlled vocabularies (Task 3). This format should be flexible enough to allow for future extensions or modifications without significant rework.
• Provide source selection configuration for ePO: The contractor will provide an example configuration to address issues related to ePO.
• Implement the selection mechanism: The contractor will implement source selection the using the previously agreed configuration format.
• Model2Owl documentation for source selection: The contractor will update the Model2Owl documentation detailing the source selection process, how to include the new configurations.

Important

The following pre-existing tickets must be also resolved in this context: model2owl#225, model2owl#202

[gkostkowski]

The description below presents the solution design that was discussed during an early feedback meeting. The solution includes specification of the status representation and model2owl configuration.

List of status values

The status-based filtering feature will be fully configurable. That means that no assumptions about any fixed status value will be made. A list of used statuses describing a UML element needs to be established for a project that uses model2owl.
One possible set of statuses that could be used is the one defined for the ePO project, that is described in the ePO Workflow Documentation (draft):

• Proposed: The concept is under Working Group discussion or has not been discussed yet. In the latter case, the concept is in the “sandbox” subfolder of the CM file.
• Approved: The concept has a Working Group approval tag and should be moved to its respective module subfolder.
• Implemented: The concept has been published in the current stable ePO release or is ready for publication in the upcoming release.

How status will be represented

The proposed way to set a status for a UML element is by using UML tags (tagged values). For a project, a special datatype property to describe the status should be chosen. Then tags using a compact URI representing that property should be set for UML elements for which the status-based filtering feature needs to be applied. In addition to that explicit method, status-based filtering could be applied to other elements that don't have the tag set (yet). For these, the default status set in the configuration will be applied.
The screenshot below depicts a tag set for a class in Enterprise Architect. The used tag is only for illustration purposes, the used tag key and value are not the part of the solution.

model2owl status configuration

The following four configuration parameters defined in the config-parameters.xsl are foreseen:

1. statusProperty
   • A compact URI of a property to be used as the key in tags describing UML element status. Such tags will be interpreted by model2owl and the element they describe will or won't be generated depending the tag value and model2owl configuration (excludedElementStatusesList)
   • XML representation: <xsl:variable name="statusProperty" select="'<status-property>'"/> where <status-property> stands for the compact URI of choice (e.g. adms:status)
   • A tag with a key specified in the statusProperty is not materialized in model2owl artefacts. It is used only to control what should be generated.
2. excludedElementStatusesList
   • Lists statuses that cause a UML element to be excluded from generation in model2owl artefacts
   • The value must be defined in validStatusesList
   • XML representation: <xsl:variable name="excludedElementStatusesList" select="('proposed', 'approved')"/>
3. unspecifiedStatusInterpretation
   • Specifies the default status describing a UML element that has no status set. The property affects only these elements that have no tag with the key defined by statusProperty configuration property set
   • The decision on whether to filter such an element is done in the usual way (the element representation is generated only if the default status value is not among statuses defined on the excludedElementStatusesList list)
   • The value must be defined in validStatusesList
   • XML representation: <xsl:variable name="unspecifiedStatusInterpretation" select="'proposed'"/>
4. validStatusesList
   • The property lists all possible, valid values for a status of a UML element
   • Status tags (specified by statusProperty) of every UML element as well as values in excludedElementStatuseslist parameters are validated based in the parameter.
   • Detection of a value that is not included in validStatusesList results in an error being reported in the conventions report
   • XML representation: <xsl:variable name="validStatusesList" select="('proposed', 'approved', 'implemented')"/>

Example

The following example presents a set of terms with their tags as well as model2owl configuration and shows the outcome in terms of what would or wouldn't be generated.

Terms and tags (input)

term	epo:status tag
:term1	proposed
:term2	approved
:term3	implemented
:term4	<not set>
:term5	work in progress

model2owl config

<xsl:variable name="statusProperty" select="'epo:status'"/>
<xsl:variable name="validStatusesList" select="('proposed', 'approved', 'implemented')"/>
<xsl:variable name="excludedElementStatusesList" select="('proposed', 'approved')"/>
<xsl:variable name="unspecifiedStatusInterpretation" select="'implemented'"/>

Outcome

term	is included in generated artefacts?
:term1	❌
:term2	❌
:term3	✔️
:term4	✔️
:term5	<error>