Skip to main content

Design abstract message tree

Wizard step 2: Message structuring and customizing​

After the starting point is selected, it is time to add the necessary sub elements and customize them. The Wizard allows you to change the structure and customize the individual elements. The order of message structuring and customizing is left to the user. You can either choose to add sub elements first and directly customize as you add them or you can first prepare the tree structure and then customize the elements. We will describe the adding of elements first and next the customization options for the elements.

2.A Structuring: Adding sub elements​

The incoming and outgoing properties of the root class selected in step 1 are loaded from the ontology and are all presented as elements that can be added as child elements of the message root element. More details about how these possible sub elements are selected can be found in the section below.

Adding sub elements can happen either by adding them one by one, or by using the 'Add all' functionality that adds all direct sub elements for this element. Note that this only adds all first level sub elements. This can be be repeated for each sub element to further expand the message model tree.

Clicking the '+' icon adds this property as a sub element of the parent element. The wizard creates a new element copy that uses the information of the property in the ontology, such as label, cardinality constraints, data type and description. Note that this copy of the ontology information is created once from the ontology information at that time. It is not synchronized to the source class in the ontology in any way, so if the ontology were to change after creating the sub element, this is not automatically translated to dependent elements.

Disabling and removing elements​

When you've made a mistake, it is possible to delete sub elements. This can be done in the parent element details section. Scroll down to sub elements and click the Trash bin icon to remove an element. This will remove the element from the message. If you want to keep the customized copy of the sub element, but you do not want it in your message, then there is the option to disable an element. This will not remove the element with its customizations. But the generators will not display this item along with any child items of this disabled item.

When developing an ontology, that keeps changing, it is necessary to use the remove instead of disable feature. Removing the sub element will make sure that you use the new ontology when you re-create the same subelement.

You can recognize a disabled item by the unchecked checkbox, and a removed (or non-existent) item by the '+' icon.

2.B. Customizing elements​

Often message models will need to further explain, restrict more or alter elements compared to the original ontology. Common ontologies are designed for re-use, often defined more broadly to support different use cases. E.g., a person may have multiple e-mail addresses in the ontology, but a message model may restrict this to a maximum of one e-mail address per person. The Wizard allows this further restriction, and this can be done after the sub element is created.

After a sub element is created using the default ontology information, such as label and cardinality constraints
Allowed customizations include renaming and adding further restrictions to the default ontological specifications into a customized message specification. For example, changing the cardinality of some property from [0..n] to [1..n] counts as a further restriction. To prevent cardinality violations of the ontology, the wizard disallows loosening constraints, e.g., changing the cardinality from [0..1] to [0..n]. The wizard also allows some structural customizations, e.g., adding a property more than once (under a different name) or inserting a grouping element (e.g., introducing a tag PersonInformation between Person and PhoneNumber, MailAddress, etc. even though the source ontology does not specify the concept of PersonInformation).

For example, an identifier type in the buyer part of an invoice message should have the value of 'KVK'. This additional value constraint can be added to this element. Other parts of the message can have different or no value constraints for this property, but for a buyer this should have the value of 'KVK'.

Another example is the usage note that can be added to the element. A usage note explains more specifically how this (often more generic) part should be specifically filled in this message and use case.

This procedure can be repeated for each element that sources from the root element, further unfolding the graph until all desired information is included in the message model. Note that ‘walking back’ over properties, i.e. going from range to domain, is only supported for object properties. This requires to include a wizard-specific annotation in the ontology.

The result of this step is an abstract message tree (AMT) that contains all necessary information for the API contract (element names, cardinalities, sequences, value restrictions and semantic mapping). This AMT is used by the different generators to generate schemas for a specific target syntax.

Explanation: How does the wizard select properties as possible sub elements?​

This section details how the current Wizard implementation browses through the ontology in order to find and present sub elements. There are different ontology modelling options to specify relevant properties for a given class. The Wizard recognizes the following options:

1. Properties that have the class specified as domain​

The properties that have explicitly specified a rdfs:domain are shown as possible sub elements for the given class.

For example:

:knows 
    a owl:ObjectProperty ;
    rdfs:domain :Person .

Union of classes are also supported. For example:

:hasNickName 
    a owl:ObjectProperty ;
    rdfs:domain owl:unionOf(:Person :Animal) .

2. Properties from class restrictions​

Properties that are mentioned in a class restriction owl:onProperty are shown as possible sub elements for the given class.

The following example expresses the statement that Person is a subclass of all things that may only participate once in the property isMarriedTo. In this way, you don't have to explicitly specify that the domain of isMarriedTo is a Person, but the wizard will induce it from the subclass restriction:

:Person 
    a owl:Class ;
    rdfs:subClassOf [
        a owl:Restriction ;
        owl:onProperty :isMarriedTo ;
        owl:maxCardinality 1
    ] .

3. Properties from SHACL property shapes that target the class​

Properties that are mentioned in a SHACL property shape sh:path that target the class are shown as possible sub elements.

For example:

:MyCustomerShape
    a sh:NodeShape ;
    sh:targetClass :Person .
    sh:property [
        sh:path :hasMailAddress ;
        sh:maxCount 1 ;
    ] .

4. Superclasses​

If the class is a subclass of another class rdfs:subClassOf, the properties for those superclasses are also shown as possible sub elements. For each superclass the options above are taken into account. A slight caveat, though, technically we would need to include all properties that have no domain specified (meaning owl:Thing is the domain), since all classes inherit from owl:Thing. But this might explode the number of options, so we chose to not show these.

5. Other​

The Wizard is still a work in progress, and we can use your help to further develop it. Do you have any modeling options that should be supported? Or does any of the current functionality not perform in the way you expect it to. Please let us know via the Discord community portal.