added conventions checkers Worksheets

docs/modules/ROOT/pages/pages/architecture/ontology-architecture.adoc

@@ -0,0 +1,3 @@
+= eProcurement ontology architecture and formalisation specifications
+
+*[TODO: add text and pages]*

docs/modules/ROOT/pages/pages/checkers/connector-checkers.adoc

@@ -0,0 +1,10 @@
+[[tab:uml2xsd]]
+.General checkers
+[cols="^,^,^,^",options="header",]
+|===================================================================================================================================================================================================================================
+| Id                       | Severity | Name                  | Message
+| general-connector-type-1 | warning  | connector-type        | Only associations, dependecies, generalisations and realisation connectors are supported.
+| general-element-type-2   | warning  | element-type          | Only Class, Package, Datatype, Enumeration, and Object elements are supported
+| general-prefix-3         | error    | namespace definitions | The prefixes $[list of undefined prefixes] are not defined. All used namespaces shall be defined ("prefix" = "base URI"), including the default one (""="base URI").
+|===================================================================================================================================================================================================================================
+

docs/modules/ROOT/pages/pages/checkers/model2owl-checkers.adoc

@@ -0,0 +1,3 @@
+= UML Convention checker inventory
+
+*[TODO: add text and pages]*

docs/modules/ROOT/pages/pages/epo-context.adoc

@@ -0,0 +1,38 @@
+[[sec:introduction]]
+== model2owl in eProcurement context
+
+This document provides a working specification of the guidelines and conventions for the eProcurement conceptual model, such that it qualifies as suitable input for the transformation scripts meant to generate the formal eProcurement ontology.
+
+The business context and the project overview are detailed in [xref:references.adoc#ref:costetchi2020a[costetchi2020a]], while the next section provides the motivation and situates the current document within the project.
+
+=== Background
+
+In the eProcurement ontology project, the conceptual model was decided [xref:references.adoc#ref:d2.01-2017[d2.01-2017]] to be represented in _Unified Modelling Language (UML)_ [xref:references.adoc#ref:uml-userguide[uml-userguide]]. It is a visual representation language that facilitates understanding and convergence between stakeholders towards a common conceptualisation of the model.
+
+Generally, the primary application of UML [xref:references.adoc#ref:fowler2004[fowler2004]] for ontology design is in the specification of class diagrams initially conceived for object-oriented software. UML does not define a formal semantics that would permit to determine, from the class diagrams, whether an ontology is consistent, or to determine the correctness of the ontology implementation. Semantics in such cases becomes a subject to interpretation by the stakeholders involved in the development process and later by the users in the application and integration tasks [xref:references.adoc#ref:grunninger2003[grunninger2003]].
+
+On the other hand, UML is closer than more logic-oriented approaches to the programming languages in which enterprise applications are implemented. For this reason the current specification establishes conventions for interpretation of the UML-based conceptual model.
+
+The UML Conceptual Model of the eProcurement domain serves as the single source of truth, which means that the formal eProcurement ontology is derived from it through a model transformation process. It is possible to generate automatically the formal ontology in RDF format [xref:references.adoc#ref:rdf11[rdf11]] from the XMI (v.2.5.1) serialisation [xref:references.adoc#ref:xmi2.5.1[xmi2.5.1]] of an UML (v.2.5) model [xref:references.adoc#ref:uml2.5[uml2.5]], provided that a set of clear transformation rules are established [xref:references.adoc#ref:costetchi2020c[costetchi2020c]], and that a set of modelling conventions is respected.
+
+This document provides the UML modelling constraints and a set of conventional and technical recommendations for naming and structuring the UML class diagram elements: packages, classes, data types, enumerations, enumeration items, class attributes, association relation and dependency relation. There are additional elements which will be addressed contextually in the following sections.
+
+[[sec:requirements]]
+=== Requirements
+
+The eProcurement conceptual model must fulfil mainly four fundamental objectives.
+
+* Facilitate understanding/comprehension of the represented system
+* Promote efficient conveyance of system details between team members and external stakeholders.
+* Provide a point of reference for system designers to gather system specifications and documentation.
+* Serve as input for development of a (more) formal model.
+
+In order to support objectives a conceptual model should fulfil the following requirements.
+
+* Be available to all team members, to facilitate collaboration and iteration.
+* Be easily changeable, as a continuous reflection of up-to-date information.
+* Contain both visual and written forms of diagramming, to better explain the abstract concepts it may represent.
+* Establish relevant terms and concepts that will be used throughout the project.
+* Define said terms and concepts.
+* Provide a basic structure for entities of the project.
+* Reduce the ambiguity while maintaining a simple and concise encoding.

docs/modules/ROOT/pages/pages/index.adoc

@@ -0,0 +1,23 @@
+# model2owl Project Documentation
+:description: The documentation for the model2owl project.
+:sectanchors:
+//:url-repo: https://github.com/SEMICeu/style-guide
+//:favicon: ../favicon.ico
+:license-url: https://creativecommons.org/licenses/by/4.0/deed.en
+:license-title: CC BY 4.0
+:docinfo: shared
+
+
+The *model2owl* https://github.com/OP-TED/model2owl/[GitHub project] comprises a set of tools for transforming a UML (v2.5) model from its XMI (v2.5.1) serialisation into the formal ontology and associated SHACL data shapes. This transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in this documentation. In addition, we provide a UML conventions checker that validates the conformity of the input XMI.
+
+This documentation covers all the important aspects that one might be interested in when using these tools, including:
+
+* The architectural setup of the project and the ontology
+* The conceptual model conventions that the UML model should adhere to, in order to allow the tools to generate the best possible results.
+* The transformation rules applied in the process of conversion
+* ...
+
+This work is developed in the context of https://github.com/eprocurementontology/eprocurementontology[eProcurement ontology project] financed by the Digital Europe Programme and led by the https://op.europa.eu/en/[Publications Office of the European Union].
+
+The tools can be used on any other ontology that is built according to the xref:architecture/ontology-architecture.adoc[architectural design] and xref:uml/conceptual-model-conventions.adoc[conceptual model conventions] described in this documentation.
+

docs/modules/ROOT/pages/pages/references.adoc

@@ -0,0 +1,97 @@
+- *[[[ref:skos-spec]]skos-spec]*
+Miles, Alistair, and Sean Bechhofer. 2009. “SKOS Simple Knowledge Organization System Reference.” \{W3C} Recommendation. W3C.
+
+- *[[[ref:uml-userguide]]uml-userguide]*
+Booch, Grady, James Rumbaugh, and Ivar Jacobson. 2005. _Unified Modeling Language User Guide, the (2nd Edition) (Addison-Wesley Object Technology Series)_. Addison-Wesley Professional.
+
+- *[[[ref:guarino2009ontology]]guarino2009ontology]*
+Guarino, Nicola, Daniel Oberle, and Steffen Staab. 2009. “What Is an Ontology?” In _Handbook on Ontologies_, 1–17. Springer.
+
+- *[[[ref:studer1998]]studer1998]*
+Studer, Rudi, V Richard Benjamins, and Dieter Fensel. 1998. “Knowledge Engineering: Principles and Methods.” _Data & Knowledge Engineering_ 25 (1-2): 161–97.
+
+- *[[[ref:owl1]]owl1]*
+Dean, Mike, and Guus Schreiber. 2004. “OWL Web Ontology Language Reference.” \{W3C} Recommendation. W3C. Available at: http://www.w3.org/TR/2004/REC-owl-ref-20040210/ .
+
+- *[[[ref:owl2]]owl2]*
+Motik, Boris, Bijan Parsia, and Peter Patel-Schneider. 2012. “OWL 2 Web Ontology Language Structural Specification and Functional-Style Syntax (Second Edition).” \{W3C} Recommendation. W3C. Available at: http://www.w3.org/TR/2012/REC-owl2-syntax-20121211/ .
+
+- *[[[ref:owl2.0]]owl2.0]*
+Motik, Boris, Bijan Parsia, and Peter Patel-Schneider. 2009. “OWL 2 Web Ontology Language Structural Specification and Functional-Style Syntax.” \{W3C} Recommendation. W3C. Available at: http://www.w3.org/TR/2009/REC-owl2-syntax-20091027/ .
+
+- *[[[ref:rdf11]]rdf11]*
+Wood, David, Richard Cyganiak, and Markus Lanthaler. 2014. “RDF 1.1 Concepts and Abstract Syntax.” \{W3C} Recommendation. W3C.
+
+- *[[[ref:costetchi2020a]]costetchi2020a]*
+Costetchi, Eugeniu. 2020a. “[.nocase]#eProcurement# Ontology Architecture and Formalisation Specifications.” Recommendation. Publications Office of the European Union.
+
+- *[[[ref:d2.01-2017]]d2.01-2017]*
+Dekkers, Makx, Emidio Stani, Brecht Wyns, and Florian Barthelemy. 2017. “D02.01 - Specification of the Process and Methodology to Develop the eProcurement Ontology with Initial Draft of the eProcurement Ontology for 3 Use Cases.” Deliverable SC378DI07171. Publications Office of the European Union.
+
+- *[[[ref:fowler2004]]fowler2004]*
+Fowler, Martin. 2004. _UML Distilled: A Brief Guide to the Standard Object Modeling Language_. Addison-Wesley Professional.
+
+- *[[[ref:grunninger2003]]grunninger2003]*
+Grunninger, Michael. 2003. “Enterprise Modelling.” In _Handbook on Enterprise Architecture_, 515–41. Springer.
+
+- *[[[ref:xmi2.5.1]]xmi2.5.1]*
+“XML Metadata Interchange (XMI) Specification: Version 2.5.1.” 2015. Standard formal/2015-06-07. Object Management Group (OMG). http://www.omg.org/spec/XMI/2.5.1.
+
+- *[[[ref:uml2.5]]uml2.5]*
+Cook, Steve, Conrad Bock, Pete Rivett, Tom Rutt, Ed Seidewitz, Bran Selic, and Doug Tolbert. 2017. “Unified Modeling Language (UML) Version 2.5.1.” Standard formal/2017-12-05. Object Management Group (OMG). https://www.omg.org/spec/UML/2.5.1.
+
+- *[[[ref:costetchi2020c]]costetchi2020c]*
+———. 2020c. “[.nocase]#eProcurement# UML Conceptual Model to OWL Ontology Transformation.” Recommendation. Publications Office of the European Union.
+
+- *[[[ref:rfc2119]]rfc2119]*
+Bradner, Scott O. 1997. “[.nocase]#Key words for use in RFCs to Indicate Requirement Levels#.” Request for Comments. RFC 2119; RFC Editor. https://doi.org/10.17487/RFC2119.
+
+- *[[[ref:rfc6919]]rfc6919]*
+Rescorla, Eric, Richard Barnes, and Stephen Kent. 2013. “[.nocase]#Further Key Words for Use in RFCs to Indicate Requirement Levels#.” Request for Comments. RFC 6919; RFC Editor. https://doi.org/10.17487/RFC6919.
+
+- *[[[ref:xml-namespaces]]xml-namespaces]*
+Layman, Andrew, Tim Bray, Henry Thompson, Dave Hollander, and Richard Tobin. 2009. “Namespaces in XML 1.0 (Third Edition).” \{W3C} Recommendation. W3C.
+
+- *[[[ref:urn-rfc8141]]urn-rfc8141]*
+Saint-Andre, P, and J Klensin. 2017. “Uniform Resource Names (URNs).” _Internet Engineering Task Force (IETF), RFC_ 8141.
+
+- *[[[ref:xml1-spec]]xml1-spec]*
+Bray, Tim, Michael Sperberg-McQueen, Eve Maler, François Yergeau, and Jean Paoli. 2008. “Extensible Markup Language (XML) 1.0 (Fifth Edition).” \{W3C} Recommendation. W3C.
+
+- *[[[ref:urn-rfc2141]]urn-rfc2141]*
+Moats, Rayan. 1997. “URN Syntax.” _Internet Engineering Task Force (IETF), RFC_. RFC Editor.
+
+- *[[[ref:d3.1-2015]]d3.1-2015]*
+PwC EU Services. 2011. “D3.1 - Process and Methodology for Core Vocabularies.” Deliverable. ISA programme of the European Commission.
+
+- *[[[ref:xml11-spec]]xml11-spec]*
+Paoli, Jean, François Yergeau, Michael Sperberg-McQueen, Tim Bray, Eve Maler, and John Cowan. 2006. “Extensible Markup Language (XML) 1.1 (Second Edition).” \{W3C} Recommendation. W3C.
+
+- *[[[ref:shacl-spec]]shacl-spec]*
+Knublauch, Holger, and Dimitris Kontokostas. 2017. “Shapes Constraint Language (SHACL).” \{W3C} Recommendation. W3C.
+
+- *[[[ref:isaHandbook2015]]isaHandbook2015]*
+———. 2015. “E-Government Core Vocabularies Handbook.” Report. ISA programme of the European Commission. https://doi.org/doi:10.2799/945287.
+
+- *[[[ref:xsd1.1-spec]]xsd1.1-spec]*
+Peterson, David, Ashok Malhotra, Sandy Gao, Michael Sperberg-McQueen, Paul V. Biron, and Henry Thompson. 2012. “W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes.” \{W3C} Recommendation. W3C.
+
+- *[[[ref:noy2001]]noy2001]*
+Noy, Natalya F, Deborah L McGuinness, et al. 2001. “Ontology Development 101: A Guide to Creating Your First Ontology.” Stanford knowledge systems laboratory technical report KSL-01-05 ...
+
+- *[[[ref:rfc3986]]rfc3986]*
+Berners-Lee, Tim, Roy T. Fielding, and Larry M Masinter. 2005. “Uniform Resource Identifier (URI): Generic Syntax.” Request for Comments. RFC 3986; RFC Editor. https://doi.org/10.17487/RFC3986.
+
+- *[[[ref:org-ontology]]org-ontology]*
+Reynolds, Dave. 2014. “The Organization Ontology.” \{W3C} Recommendation. W3C.
+
+- *[[[ref:dublin-core-metadata]]dublin-core-metadata]*
+Kunze, John, and Thomas Baker. 2007. “The Dublin Core Metadata Element Set.” RFC 5013, August.
+
+- *[[[ref:semic-defs]]semic-defs]* Principles for creating good definitions_v1.00. Available at: https://github.com/SEMICeu/OpenGuidelines/blob/main/Principles%20for%20creating%20good%20definitions_v1.00.pdf
+
+- *[[[ref:semic-style-guide]]semic-style-guide]* SEMIC Style guide v1.0.0, 2023, https://semiceu.github.io/style-guide/public-review/index.html
+
+- *[[[ref:epo-arch]]epo-arch]* Costetchi, E. (2020). EProcurement ontology architecture and formalisation specifications. Recommendation, Publications Office of the European Union. Available at: https://github.com/OP-TED/model2owl/blob/master/doc/ontology-architecture/ontology-architecture.pdf
+
+- *[[[ref:oslo-rules]]oslo-rules]* Thijs, G. (2019) OSLO MODELLERINGSREGELS. Available at: https://github.com/Informatievlaanderen/OSLO-handleiding/blob/master/Modellering/OSLO-Modelleringsregels.pdf

docs/modules/ROOT/pages/pages/transformation/uml2owl-transformation.adoc

@@ -0,0 +1,3 @@
+= Transformation of the UML model into derivative artefacts
+
+*[TODO: add text and pages]*

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

@@ -0,0 +1,11 @@
+= 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.
+
+.In the following sections we describe *[TODO: update this list]*:
+
+* the context (including the requirements and assumptions) for defining these conventions
+* some of the key terms and concepts used
+* the general conventions
+* the technical conventions
+* ...

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

@@ -0,0 +1,83 @@
+== Conventions on uml:Attribute elements
+
+[[sec:attributes]]
+=== Conventional recommendations on Attributes
+
+[[sec:attributes-names-with-verb]]
+|===
+|{set:cellbgcolor: #a8c6f7}
+ *Title:* Attribute names
+
+|{set:cellbgcolor: #f5f8fc}
+*Identifier* -
+
+|*Statement:*
+It is recommended to use a verb in the attribute name, such as "has-" or "is-".
+|===
+
+*Description:*
+
+When creating attribute names, it is conventional to use simple nouns such as "name", "weight", "colour". Attributes are a special type of relations that describe an entity in terms of its qualities. And so, to be consistent with the above convention and in order to increase the clarity, it is recommended to employ the prefix "has-" for each attribute, even if it does not add much to the term's meaning. So, it is preferred to use terms such as "hasName", "hasWeight" and "hasColour".
+
+It is recommended to use simple nouns for attribute names prepended with the verb "has-".
+
+It is recommended to avoid duplicate attribute names across multiple classes. Unless, by design, attributes with the same name are shared across multiple classes.
+
+// To avoid laborious mechanical work of adding the prefix, it is possible to rely on the convention that the attribute names starting with a capital letter must be read as having the "has-" prefix. It means that the transformation script will prepend the "has-" prefix to all attributes starting with a capital letter.
+
+[[sec:attributes-multiplicity]]
+|===
+|{set:cellbgcolor: #a8c6f7}
+ *Title:* Attribute multiplicity
+
+|{set:cellbgcolor: #f5f8fc}
+*Identifier* -
+
+|*Statement:*
+Attributes shall be assigned cardinality specifications contextualised to the class carrying them.
+|===
+
+*Description:*
+
+The attribute multiplicity should be specified indicating the minimum and maximum cardinality. The default [1] multiplicity shall be interpreted as unspecified, and expressed as [0..*] in the OWL model.
+
+In special cases, a list of custom default multiplicities is defined for the transformation script. That means that some data types or classes that are used as attribute types are paired with a default multiplicity, for example "1..1", "0..1", "2..2".
+
+[[sec:attributes-class]]
+=== uml:Class attributes
+
+[[sec:attributes-datatypes]]
+|===
+|{set:cellbgcolor: #a8c6f7}
+ *Title:* Attribute datatypes
+
+|{set:cellbgcolor: #f5f8fc}
+*Identifier* -
+
+|*Statement:*
+uml:Attribute shall be defined with generally accepted primitive datatypes.
+|===
+
+*Description:*
+
+Each uml:Attribute must have a name and an attribute type. uml:Attribute is mostly transformed into owl:DataProperty and in some controlled cases into owl:ObjectProperty. High preference shall be given to using OWL 2 compliant XSD [xref:references.adoc#ref:xsd[xsd]] and RDF [xref:references.adoc#ref:rdf[rdf]] standard datatypes. [xref:uml/conv-datatypes.adoc#sec:primitive-datatypes[see Section on Primitive Data types]]
+
+In cases when a property needs to be defined as ranging on an unknown controlled list or authority table constitute a special case. They can be expressed as uml:Attribute with the datatype `skos:Concept`. These attributes are transformed into owl:ObjectProperty in a manner similarly to uml:Association.
+
+An attribute may contain an alias, used as an alternative label. It can be specified via uml:Tags. [xref:uml/conv-general.adoc#sec:tags[See section on uml:Tags]]
+
+[[sec:attributes-reuse]]
+|===
+|{set:cellbgcolor: #a8c6f7}
+ *Title:* Attribute name reuse
+
+|{set:cellbgcolor: #f5f8fc}
+*Identifier* -
+
+|*Statement:*
+Attribute names can be reused only as attributes in other classes, not as relations.
+|===
+
+*Description:*
+
+It is mandatory to avoid using the same name in an attribute and in a relation, unless an additional rule that handles intentional exceptions exists.