Addressed all TODOs that could be addressed, and left some (commented…

… out) for future versions.

docs/modules/ROOT/nav.adoc

@@ -4,7 +4,6 @@
 
 * xref:uml/definitions.adoc[Definitions]
 * xref:uml/conceptual-model-conventions.adoc[UML Model Conventions]
-** xref:uml/on-conventions.adoc[On Conventions]
 ** xref:uml/conv-general.adoc[General Conventions]
 ** xref:uml/conv-classes.adoc[Classes]
 ** xref:uml/conv-attributes.adoc[Class Attributes]

docs/modules/ROOT/pages/transformation/transf-rules2.adoc

@@ -405,7 +405,7 @@ Specify object property range for the target end of the dependency.
 .Range specification in Turtle syntax
 [source,Turtle]
 ----
-:relationName a owl:ObjectProperty ;
+:relationName
   rdfs:range skos:Concept ;
 .
 ----
@@ -420,7 +420,7 @@ Specify object property range for the target end of the dependency.
 ----
 |===
 
-WARNING: *TODO:* Explain that In OWL we want to state only that range is a skos:Concept, without committing to a specific list. We do this additional restriction in the data shape.
+NOTE: In OWL we want to state only that the range of a Dependency connector is a `skos:Concept`, without committing to a specific list. We do this additional restriction in the data shape.
 
 [#rule:dependency-uni-range-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Dependency range shape -- in data shape layer',reftext='{example-caption} {rule-cnt}']
 ====

docs/modules/ROOT/pages/transformation/transf-rules3.adoc

@@ -128,6 +128,8 @@ image::f17.png[17]
 [#fig:enumeration-owl-visual]
 image::f18.png[18]
 
+IMPORTANT: Normally, the controlled list represented by UML Enumerations will be defined externally. In order to be ale to validate some data against the generate SHACL shapes, these controlled lists need to be imported into the SHACL shapes. Moreover, the restriction module should be also imported into the SHACL module, alongside the OWL core module.
+
 
 [#rule:enumeration-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D01}. Enumeration -- in core ontology layer',reftext='{example-caption} {rule-cnt}']
 ====
@@ -191,11 +193,6 @@ For a UML enumeration, specify an equivalent class restriction covering the set
 ----
 |===
 
-WARNING: Should this be subclass of `skos:Concept` or `skos:ConceptScheme`? More likely the latter. Update if confirmed.
-
-WARNING: *TODO:* Explain that we expect the controlled list to be defined externally and be imported into the SHACL shapes. +
-*TODO:* Explain that the restriction module should be imported into the SHACL module alongside the OWL core module.
-
 [#rule:enumeration-item-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D01}. Enumeration items -- in core ontology layer',reftext='{example-caption} {rule-cnt}']
 ====
 Specify SKOS concept instantiation axiom for each UML enumeration item.

docs/modules/ROOT/pages/transformation/transf-rules4.adoc

@@ -183,7 +183,6 @@ In accordance with , every kind of UML Element may own Comments (see <<fig:comme
 .Visual representation of a UML comment (on the left) and an OWL comment (on the right)
 [#fig:comment-visual]
 image::f19.png[19]
-WARNING: **TODO:** Should we update the image to better reflect how the transformation is being done now?
 
 As UML Comments add no semantics, they are not used in any method of semantic validation. In OWL the AnnotationAssertion axiom does not add any semantics either, and it only improves readability.
 
@@ -263,11 +262,11 @@ shape:ClassName-PropertyName
     <sh:description>This is an additional comment on PropertyName</sh:description>
 </rdf:Description>
 ----
-WARNING: *QUESTION:* should we use here `rdfs:comment` instead of adding a second value to `sh:description`?
+//WARNING: TODO: *QUESTION:* should we use here `rdfs:comment` instead of adding a second value to `sh:description`?
 |===
 
 
-WARNING: TODO: Discuss whether we should include language tags (by default, or if explicitly specified in the model, or if controlled by configuration)?
+// TODO: Discuss whether we should include language tags (by default, or if explicitly specified in the model, or if controlled by configuration) for comments, notes and/or labels.
 
 === Tags
 

docs/modules/ROOT/pages/uml/conceptual-model-conventions.adoc

@@ -1,6 +1,31 @@
 = UML Conceptual Model Conventions
 
-This part of the *model2owl* project documentation describes _the conventions that the UML conceptual model should adhere to_ in order to allow the tools provided within the *model2owl* project to generate the best possible result, i.e. the most complete and correct OWL ontologies and SHACL shapes.
+This part of the *model2owl* project documentation describes _the conventions that the UML conceptual model should adhere to_ in order to allow the tools provided within the *model2owl* project to generate the best possible derivate artefacts, i.e. the most complete and correct OWL ontologies and SHACL shapes.
+
+
+[[sec:on-conventions]]
+== UML Model Conventions
+
+The current set of UML Model Conventions are meant to guide the semantic engineers and ontology editors on producing consistent, uniform and uniquely interpretable conceptual models. Also, it is meant to help the readers of the conceptual models to interpret the meaning and eliminate any ambiguities. Finally, the conventions are fit for implementation.
+
+This set of guidelines is aligned with the SEMIC style guide [xref:references.adoc#ref:semic-style-guide[semic-style-guide]] and constitutes an extension and further elaboration of it.
+
+The guidelines provided here are either of general or technical nature. They are formulated so, as to be not only easily understandable by the semantic engineer, but also to allow the implementation of automatic model checkers (see Section xref:checkers/model2owl-checkers.adoc[]]) as well as the definition of precise transformation rules that can be implemented in tools to automatically generate the semantic derivate artefacts (see Section xref:transformation/uml2owl-transformation.adoc[]]).
+
+We organized the conventions into subsections covering:
+
+* general conventions, which apply to multiple model components
+* conventions specific to particular UML elements (Classes and their Attributes, Data Types, Enumerations, Objects, Packages)
+* general conventions on UML connectors
+* conventions specific to particular UML connector types (Associations, Dependencies, Generalisations, Realisations)
+
+
+[[sec:keywords]]
+== Key words for Requirement Statements
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [xref:references.adoc#ref:rfc2119[rfc2119]].
+
+The key words "MUST (BUT WE KNOW YOU WON’T)", "SHOULD CONSIDER", "REALLY SHOULD NOT", "OUGHT TO", "WOULD PROBABLY", "MAY WISH TO", "COULD", "POSSIBLE", and "MIGHT" in this document are to be interpreted as described in RFC 6919 [xref:references.adoc#ref:rfc6919[rfc6919]].
 
 .In the following sections we describe *[TODO: update this list]*:
 

docs/modules/ROOT/pages/uml/conv-conn-association.adoc

@@ -17,7 +17,7 @@ uml:Association elements connect two uml:Classes, or a uml:Class to a uml:Object
 
 The uml:Association connectors represent relations between source and target classes, or a source class and an object target. The association connector cannot be used between other kinds of UML elements.
 
-*[TODO:]* Should we include here what is the OWL interpretation of these two kinds of association relations? Is it `someValuesFrom` and `hasValue` respectively, or will it be domain/range specification, at least in case of class-to-class association (in the reasoning layer)? Or should this be only described in the transformation rules?
+//[TODO: Should we include here what is the OWL interpretation of these two kinds of association relations? Is it `someValuesFrom` and `hasValue` respectively, or will it be domain/range specification, at least in case of class-to-class association (in the reasoning layer)? Or should this be only described in the transformation rules?]
 
 [[rule:association-target]]
 |===

docs/modules/ROOT/pages/uml/conv-conn-realization.adoc

@@ -18,7 +18,7 @@ uml:Realization connectors connect a uml:Object element to a uml:Class or uml:En
 
 The uml:Realization connector signifies an instantiation relation, and is transformed into `rdf:type` relation standing between the source object and the target class. In case the target is a uml:Enumeration element (and the enum is converted into a `skos:ConceptScheme` instance, and the object into a `skos:Concept`), then the relation should be translated into a `skos:inScheme` relation.
 
-[TODO:] Check if the last sentence is correct. Also, wouldn't it be more appropriate if we would use a "composition", or at least "aggregation", relation to connect object to enums?
+//[TODO:] Check if the last sentence is correct. Also, wouldn't it be more appropriate if we would use a "composition", or at least "aggregation", relation to connect object to enums?
 
 
 [[rule:realization-name]]

docs/modules/ROOT/pages/uml/conv-enumerations.adoc

@@ -22,10 +22,13 @@ An uml:Enumeration element is transformed into `skos:ConceptScheme`, and an enum
 *Description:*
 
 
-Each uml:Enumeration element is transformed into skos:ConceptScheme, and each enumeration item (represented by an uml:Attribute) is transformed into a skos:Concept. An enumeration must not be empty. [TODO: Is this last sentence still valid? How about in case of Enumerations that refer to external controlled lists? If this is statement is valid, would it make sense to make sense to create a separate rule for it?]
+Each uml:Enumeration element is transformed into skos:ConceptScheme, and each enumeration item, if present as an uml:Attribute value, is transformed into a `skos:Concept`. An enumeration might be empty, especially when they refer to externally specified controlled lists.
 
-In a uml:Enumeration element, the name shall be interpreted as the controlled list name; it must be a normalised string. Each attribute name is used as a local segment in the generation of the concept URI. The attribute type is ignored and by default is considered to be skos:Concept. The attribute alias is transformed into skos:Concept preferred label. The attribute initial value is transformed into the alternative label of the concept. If the attribute alias is longer than the attribute initial value, then it is considered that the two fields have been swapped by mistake. [TODO: Check whether these assumptions and manipulations are still valid]
+//TODO We need in fact a flag that controlled whether the Enum definitions shall be present in the core layer (at all), or not.
+
+In a uml:Enumeration element, the name shall be interpreted as the controlled list name; it must be a normalised string. Each attribute name is used as a local segment in the generation of the concept URI. The attribute type is ignored and by default is considered to be `skos:Concept`. The attribute alias is transformed into the `skos:Concept`s preferred label. The attribute initial value is transformed into the alternative label of the concept.
+//TODO see if we need to specify additional rules for this.
 
 In case no attribute alias is specified then the attribute name is used as preferred label of the skos:Concept. This happens as skos:prefLabel is a mandatory property in the SKOS model.
 
-It is possible to employ the enumerations for class properties by drawing a dependency (uml:Dependency) relation from the class to the enumeration and provide a relation target role. However, the enumeration should not connect to other elements. [TODO: Check whether we shouldn't talk about Object to Enum relationships here]
+It is possible to employ the enumerations for class properties by drawing a dependency (uml:Dependency) relation from the class to the enumeration and provide a relation target role. However, the enumeration should not connect to other elements.

docs/modules/ROOT/pages/uml/conv-general.adoc

@@ -182,7 +182,7 @@ In UML, the spaces in names are allowed and using them may be the most intuitive
 
 It is recommended that the element names avoid using spaces and instead follow a camel-case convention. _CamelCasing_ is the practice of writing phrases such that the word or abbreviation in the middle of the phrase begins with a capital case.
 
-[TODO: Check if the following is still holds]
+//[TODO: Check if the following is still holds]
 Exceptionally, if the conceptual model authors must maintain high readability of the UML diagrams, spaces may be tolerated and handled by the conversion script. In the conversion process, spaces are trimmed and phrases turned into camel-case form. For example " Pre-award catalogue request " is transformed into "Pre-AwardCatalogueRequest".
 
 [[sec:uniqueness]]
@@ -391,7 +391,8 @@ The properties having this controlled list as range shall be depicted as UML dep
 
 image::cmc-r14-1.png[]
 
-The name of the Enumeration shall be resolved to a URI identical to that of the `skos:ConceptScheme`. As for the connector type we recommend using a dependency connector (depicted with a dashed line) because the semantic interpretation differs slightly from the association connector (depicted with a continuous line). Namely, the range of the property has to fulfil two constraints: (a) instantiating the skos:Concept class and (b) being `skos:inScheme` the intended controlled list [xref:references.adoc#ref:epo-arch[epo-arch]]. [TODO: update reference]
+The name of the Enumeration shall be resolved to a URI identical to that of the `skos:ConceptScheme`. As for the connector type we recommend using a dependency connector (depicted with a dashed line) because the semantic interpretation differs slightly from the association connector (depicted with a continuous line). Namely, the range of the property has to fulfil two constraints: (a) instantiating the `skos:Concept` class and (b) being `skos:inScheme` the intended controlled list [xref:references.adoc#ref:epo-arch[epo-arch]].
+//TODO: this reference can be replaced with a cross-reference to the architecture section of this Model2OWL documentation, when that part will be updated.