From 08e9e65d9c46b6019cd91f71870357444f77d239 Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 16:55:35 +0600 Subject: [PATCH 01/18] [PRJ-13] Fix links to ontology-architecture.pdf Link to the resource as it is on the official OP-TED GitHub repository (which is already the one listed under references). Resolves internal feedback issue PRJ-13. --- docs/modules/ROOT/pages/index.adoc | 4 ++-- docs/modules/ROOT/pages/references.adoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index afaca50..1e4943c 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -8,7 +8,7 @@ :docinfo: shared -The https://github.com/OP-TED/model2owl/[*model2owl*] project comprises a set of tools for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/meaningfy-ws/model2owl/blob/master/doc/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. +The https://github.com/OP-TED/model2owl/[*model2owl*] project comprises a set of tools for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in the https://meaningfy-ws.github.io/model2owl-docs/public-review/uml/conceptual-model-conventions.html[EPO UML conventions specification]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. @@ -29,5 +29,5 @@ This documentation is evolving and aims at covering the important aspects that o 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 provided https://github.com/meaningfy-ws/model2owl/blob/master/doc/ontology-architecture/ontology-architecture.pdf[modelling architecture] and xref:uml/conceptual-model-conventions.adoc[UML conceptual model conventions]. +The tools can be used on any other ontology that is built according to the provided https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[modelling architecture] and xref:uml/conceptual-model-conventions.adoc[UML conceptual model conventions]. diff --git a/docs/modules/ROOT/pages/references.adoc b/docs/modules/ROOT/pages/references.adoc index b264106..177c34e 100644 --- a/docs/modules/ROOT/pages/references.adoc +++ b/docs/modules/ROOT/pages/references.adoc @@ -89,7 +89,7 @@ Kunze, John, and Thomas Baker. 2007. “The Dublin Core Metadata Element Set.” - *[[[ref:semic-style-guide]]semic-style-guide]* SEMIC Style guide v1.0.0, 2023, https://semiceu.github.io/style-guide/1.0.0/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: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/docs/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 From f52cf4d2809d42e64d24bd0dddb5bc6e553c3c99 Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 17:51:36 +0600 Subject: [PATCH 02/18] [PRJ-1] Make ePO project relation clear at the outset Make it clear in the beginning that **model2owl** was created for the ePO project. Resolve internal feedback issue PRJ-1. --- docs/modules/ROOT/pages/index.adoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 1e4943c..ce7a7de 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -8,7 +8,7 @@ :docinfo: shared -The https://github.com/OP-TED/model2owl/[*model2owl*] project comprises a set of tools for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. +The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a set of https://en.wikipedia.org/wiki/Programming_tool[programming tools] for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in the https://meaningfy-ws.github.io/model2owl-docs/public-review/uml/conceptual-model-conventions.html[EPO UML conventions specification]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. @@ -27,7 +27,4 @@ This documentation is evolving and aims at covering the important aspects that o * The transformation rules applied in the process of conversion. * The set of validation rules that realise the established conventions (and UML interpretations). -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 provided https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[modelling architecture] and xref:uml/conceptual-model-conventions.adoc[UML conceptual model conventions]. - From 7de93ccdad468514daf2689dc20bdb77661b88b2 Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 18:16:21 +0600 Subject: [PATCH 03/18] [PRJ-5] Remove unneded word, fix official acronym Name the interdocument page cross-reference as how it appears, i.e. without mentioning "specification". Also conform to official `ePO` acronmy style. Resolves internal feedback issue PRJ-5. --- docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index ce7a7de..5fccb5d 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -10,7 +10,7 @@ The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a set of https://en.wikipedia.org/wiki/Programming_tool[programming tools] for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. -The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in the https://meaningfy-ws.github.io/model2owl-docs/public-review/uml/conceptual-model-conventions.html[EPO UML conventions specification]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. +The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in https://meaningfy-ws.github.io/model2owl-docs/public-review/uml/conceptual-model-conventions.html[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. The following capabilities are implemented: From 475738c0d958f694d8bd821a51c10a7360aa509f Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 18:20:44 +0600 Subject: [PATCH 04/18] Use internal cross-reference markup --- docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 5fccb5d..65fd357 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -10,7 +10,7 @@ The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a set of https://en.wikipedia.org/wiki/Programming_tool[programming tools] for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. -The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in https://meaningfy-ws.github.io/model2owl-docs/public-review/uml/conceptual-model-conventions.html[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. +The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in xref:uml/conceptual-model-conventions.adoc[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. The following capabilities are implemented: From b54a7d28e20d763949c292f7219c50507fc8f30f Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 18:32:31 +0600 Subject: [PATCH 05/18] [PRJ-9] Rephrase statement about evolution and usage Remove the emphasis on _important_ aspects as we want to describe exactly what is commonly understood to be aspects related to usage. Resolves internal feedback issue PRJ-9. --- docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 65fd357..28af6e5 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -20,7 +20,7 @@ The following capabilities are implemented: * UML -> OWL 2 (heavyweight ontology with additional axioms suitable for reasoning purposes) * UML -> SHACL (data shapes suitable for representing an application profile) -This documentation is evolving and aims at covering the important aspects that one might be interested in when using these tools, including: +This documentation is evolving and aims at covering the following aspects related to use of these tools: * The architectural setup of the project and the ontology * The conceptual model conventions that the UML model should adhere to, in order to enable the tools to generate the best possible results. From 55f49b38104e8425af8af2293a78a7d1f44ed69d Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 18:43:37 +0600 Subject: [PATCH 06/18] [PRJ-10] Rethink use of the word `project` It has come to our attention that mentioning "project" all the time can be confusing as this is part of an umbrella project already (ePO). Use the word `toolset` instead where this confusion is likely, and introduce that terminology early on as a precursor. Resolves internal feedback issue PRJ-10. --- docs/modules/ROOT/pages/index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 28af6e5..5ff6747 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -8,7 +8,7 @@ :docinfo: shared -The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a set of https://en.wikipedia.org/wiki/Programming_tool[programming tools] for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. +The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a _toolset_, or set of https://en.wikipedia.org/wiki/Programming_tool[programming tools], for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in xref:uml/conceptual-model-conventions.adoc[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. @@ -22,7 +22,7 @@ The following capabilities are implemented: This documentation is evolving and aims at covering the following aspects related to use of these tools: -* The architectural setup of the project and the ontology +* The architectural setup of the toolset and the ontology * The conceptual model conventions that the UML model should adhere to, in order to enable the tools to generate the best possible results. * The transformation rules applied in the process of conversion. * The set of validation rules that realise the established conventions (and UML interpretations). From f9101b29e9082636ab4575a559d722cc21062692 Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 19:03:51 +0600 Subject: [PATCH 07/18] [PRJ-12] Try to clarify transformation vs. validation rules It appears mentioning "rules" without direct context can be confusing, so add a slight bit of context to make the distinction clear. Resolves internal feedback issue PRJ-12. --- docs/modules/ROOT/pages/index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 5ff6747..4da26e0 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -10,7 +10,7 @@ The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a _toolset_, or set of https://en.wikipedia.org/wiki/Programming_tool[programming tools], for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. -The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in xref:uml/conceptual-model-conventions.adoc[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. +The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in xref:uml/conceptual-model-conventions.adoc[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. Validation rules for the transformation confirm the conformance to these conventions. The following capabilities are implemented: @@ -25,6 +25,6 @@ This documentation is evolving and aims at covering the following aspects relate * The architectural setup of the toolset and the ontology * The conceptual model conventions that the UML model should adhere to, in order to enable the tools to generate the best possible results. * The transformation rules applied in the process of conversion. -* The set of validation rules that realise the established conventions (and UML interpretations). +* The set of validation rules that check a transformation's conformance to the established conventions (and UML interpretations). The tools can be used on any other ontology that is built according to the provided https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[modelling architecture] and xref:uml/conceptual-model-conventions.adoc[UML conceptual model conventions]. From 5fd90bf10e4c627574aceb27a8d78538a638eb2e Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 19:20:08 +0600 Subject: [PATCH 08/18] [EPO-1] Make ePO project relation clear again Make clear how `model2owl` relates to the conceptual model and the ontology artifact. Resolves internal feedback issue EPO-1. --- docs/modules/ROOT/pages/epo-context.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index 1471070..9461c59 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -1,7 +1,7 @@ [[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. +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 (ePO). The https://github.com/OP-TED/model2owl/[*model2owl*] toolset, which hosts these transformation scripts, is therefore an integral part of the ePO project. 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. From 20a49998b20e21da19f1ed6e6d8866573d251c9d Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 19:31:42 +0600 Subject: [PATCH 09/18] [EPO-2] Rename page title for ePO context Be as simple as possible. Resolves internal feedback issue PRJ-2. --- docs/modules/ROOT/pages/epo-context.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index 9461c59..6c19a66 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -1,5 +1,5 @@ [[sec:introduction]] -== model2owl in eProcurement context +== Relation to ePO 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 (ePO). The https://github.com/OP-TED/model2owl/[*model2owl*] toolset, which hosts these transformation scripts, is therefore an integral part of the ePO project. From 1cda4e407e0bbfc5ef093a8952a85e66d6b6b67c Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 19:40:33 +0600 Subject: [PATCH 10/18] Rephrase ePO and procurement subject matter Try to make the relation between the ontology and its general domain subject matter clear. --- docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 4da26e0..a810d5f 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -8,7 +8,7 @@ :docinfo: shared -The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[Public Procurement Ontology (ePO)] project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a _toolset_, or set of https://en.wikipedia.org/wiki/Programming_tool[programming tools], for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. +The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[eProcurement Ontology (ePO)] public procurement digitization project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a _toolset_, or set of https://en.wikipedia.org/wiki/Programming_tool[programming tools], for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification]. The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in xref:uml/conceptual-model-conventions.adoc[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. Validation rules for the transformation confirm the conformance to these conventions. From 3afb42ef31a4c6a5bee4b419cee9a0bf428d443e Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 19:48:40 +0600 Subject: [PATCH 11/18] [EPO-3] Restructure introduction in ePO context Try to provide more clarity regarding `model2owl` and ePO. Replace citation with link to public specification. Resolves internal feedback issues EPO-3 and partially GEN-1. --- docs/modules/ROOT/pages/epo-context.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index 6c19a66..9603cc9 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -1,9 +1,9 @@ [[sec:introduction]] == Relation to ePO -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 (ePO). The https://github.com/OP-TED/model2owl/[*model2owl*] toolset, which hosts these transformation scripts, is therefore an integral part of the ePO project. +This section provides the motivation for the https://github.com/OP-TED/model2owl/[*model2owl*] software project within the https://docs.ted.europa.eu/EPO/latest/business.html[eProcurement Ontology (ePO)] project. The business context and the project overview are detailed in the https://docs.ted.europa.eu/epo-home/ePO_Arch_Design.html[eProcurement ontology architecture and formalisation specifications]. -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. +We provide here 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 https://github.com/OP-TED/model2owl/[*model2owl*] toolset, which hosts these transformation scripts, is therefore an integral part of the ePO project. === Background From 3ba386d545161087abb49dd4116a1a5dfea0da1d Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Wed, 25 Oct 2023 21:08:42 +0600 Subject: [PATCH 12/18] [EPO-4] Clarify the context of semantics Try to make clear what we mean by semantics in the UML context. Resolves internal feedback issue EPO-4 partially. --- docs/modules/ROOT/pages/epo-context.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index 9603cc9..c7c217d 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -9,7 +9,7 @@ We provide here a working specification of the guidelines and conventions for th 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]]. +Generally, the primary application of UML [xref:references.adoc#ref:fowler2004[fowler2004]] for ontology design is in the specification of class diagrams, a design formalism initially conceived for object-oriented software. UML does not define a formal _semantics_ that would permit to determine, from the class diagrams, whether a corresponding ontology is consistent, or to determine the correctness of the ontology implementation. Semantics in UML is therefore 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. From 6a93171cb45ac83180b067d4ab4631058ca9d34a Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Thu, 26 Oct 2023 14:11:59 +0600 Subject: [PATCH 13/18] [EPO-5] Rephrase enterprise applications paragraph Minor modification to make the enterprise application statement comprehensible. Resolves internal feedback issue EPO-5. --- docs/modules/ROOT/pages/epo-context.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index c7c217d..391d0aa 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -11,7 +11,7 @@ In the eProcurement ontology project, the conceptual model was decided [xref:ref Generally, the primary application of UML [xref:references.adoc#ref:fowler2004[fowler2004]] for ontology design is in the specification of class diagrams, a design formalism initially conceived for object-oriented software. UML does not define a formal _semantics_ that would permit to determine, from the class diagrams, whether a corresponding ontology is consistent, or to determine the correctness of the ontology implementation. Semantics in UML is therefore 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. +Yet, UML is closer than more logic-oriented approaches to the programming languages in which software applications -- typically https://en.wikipedia.org/wiki/Enterprise_software[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 a UML (v.2.5) model [xref:references.adoc#ref:uml2.5[uml2.5]], provided that xref:transformation/uml2owl-transformation.adoc[a set of clear transformation rules] are established, and that xref:uml/conceptual-model-conventions.adoc[a set of modelling conventions] is respected. From 2a6fd298cea8ee61967754b50e12ba92dfc51eb3 Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Thu, 26 Oct 2023 14:16:04 +0600 Subject: [PATCH 14/18] [EPO-6] Restructure part about conventions and rules Apparently it is better to put the conventions before the rules. Resolves internal feedback issue EPO-6. --- docs/modules/ROOT/pages/epo-context.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index 391d0aa..aa7ad51 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -13,7 +13,7 @@ Generally, the primary application of UML [xref:references.adoc#ref:fowler2004[f Yet, UML is closer than more logic-oriented approaches to the programming languages in which software applications -- typically https://en.wikipedia.org/wiki/Enterprise_software[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 a UML (v.2.5) model [xref:references.adoc#ref:uml2.5[uml2.5]], provided that xref:transformation/uml2owl-transformation.adoc[a set of clear transformation rules] are established, and that xref:uml/conceptual-model-conventions.adoc[a set of modelling conventions] is respected. +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 a UML (v.2.5) model [xref:references.adoc#ref:uml2.5[uml2.5]], provided that xref:uml/conceptual-model-conventions.adoc[a set of modelling conventions] is respected, and that xref:transformation/uml2owl-transformation.adoc[a set of clear transformation rules] is established. 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. These will be addressed contextually in the subsections of xref::uml/conceptual-model-conventions.adoc[UML conventions specification]. From decf15d417cd805e19883403af1104babd507afc Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Thu, 26 Oct 2023 14:24:59 +0600 Subject: [PATCH 15/18] [EPO-8] Minor modifications of model requirements Make explicit that we are talking about the eProcurement conceptual model. Resolves internal feedback issue EPO-8, partially. --- docs/modules/ROOT/pages/epo-context.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index aa7ad51..6e610a3 100644 --- a/docs/modules/ROOT/pages/epo-context.adoc +++ b/docs/modules/ROOT/pages/epo-context.adoc @@ -27,12 +27,12 @@ The eProcurement conceptual model must fulfil mainly four fundamental objectives * 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. +In order to support the objectives, the eProcurement conceptual model must fulfil the following requirements: -* Be available to all team members, to facilitate collaboration and iteration. +* Be available to all stakeholders, 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. +* Define terms and concepts. +* Provide a basic structure for the conceptual entities of the project. * Reduce the ambiguity while maintaining a simple and concise encoding. \ No newline at end of file From 178c7739eb945bd96c495846453da6b4fa42fe9f Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Thu, 26 Oct 2023 14:31:54 +0600 Subject: [PATCH 16/18] [DEF-1] Remove interchangeably from definitions Resolves internal feedback issue DEF-1. --- docs/modules/ROOT/pages/uml/definitions.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/uml/definitions.adoc b/docs/modules/ROOT/pages/uml/definitions.adoc index da981ba..6fa839f 100644 --- a/docs/modules/ROOT/pages/uml/definitions.adoc +++ b/docs/modules/ROOT/pages/uml/definitions.adoc @@ -1,7 +1,7 @@ [[sec:definitions]] == Preliminary definitions -In this document three closely related and mostly overlapping domains are used interchangeably. They come from the worlds of: _enterprise architecture_, _software engineering and design_ and _formal knowledge representation_. It is therefore necessary to establish the terms, especially the common ones, by defining what they mean in each of these domains. +This documentation makes references to three closely related and overlapping domains. They come from the worlds of: _enterprise architecture_, _software engineering and design_ and _formal knowledge representation_. It is therefore necessary to establish the terms, especially the common ones, by defining what they mean in each of these domains. [[sec:cm]] === Conceptual Model From ddaa028f27138ca501e6776ce88fac12b93dfa3f Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Thu, 26 Oct 2023 14:41:39 +0600 Subject: [PATCH 17/18] [DEF-3] Remove SKOS-specific text from concept definition We don't need to copy wholesale the SKOS definition of a concept as it is not really understandable without context ("preferred and alternative labels"?). Here it is better to be general. Resolves internal feedback issue DEF-3. --- docs/modules/ROOT/pages/uml/definitions.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/uml/definitions.adoc b/docs/modules/ROOT/pages/uml/definitions.adoc index 6fa839f..f1fecb8 100644 --- a/docs/modules/ROOT/pages/uml/definitions.adoc +++ b/docs/modules/ROOT/pages/uml/definitions.adoc @@ -6,7 +6,7 @@ This documentation makes references to three closely related and overlapping dom [[sec:cm]] === Conceptual Model -A _conceptual model_ is a representation of a system that uses concepts to form said representation. A _concept_ can be viewed as an idea or notion; a unit of thought [xref:references.adoc#ref:skos-spec[skos-spec]]. However, what constitutes a unit of thought is subjective, and this definition is meant to be suggestive, rather than restrictive. That is why each concept needs to be well named by providing preferred and alternative labels, and a clear and precise definition supported by examples and explanatory notes. +A _conceptual model_ is a representation of a system that uses concepts to form said representation. A _concept_ can be viewed as an idea or notion; a unit of thought [xref:references.adoc#ref:skos-spec[skos-spec]]. A concept needs to be well named by providing as many understandable labels as necessary (for example, multiple different expressions or languages), supported by a clear definition with examples and explanatory notes. The conceptual model comprises representations of concepts, their qualities or attributes and relationships to other concepts. Most commonly these are association and generalisation relations. In addition, behaviour can be represented, ranging from the concept level up to the level of the system as a whole. Behavioural aspects, however, fall out of the scope in the current specification, which addresses at the structural elements mainly. From e2ff2219329666c3da7e457f5a7b07512b521c5d Mon Sep 17 00:00:00 2001 From: Rashif Ray Rahman Date: Thu, 26 Oct 2023 15:19:42 +0600 Subject: [PATCH 18/18] [DEF-4] Clarify conceptual model and UML Make the relationship between conceptual model and UML easier to understand for the layman, using a bit of rephrasing and explicit examples. Resolves internal feedback issue DEF-4 and partially DEF-5. --- docs/modules/ROOT/pages/uml/definitions.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/modules/ROOT/pages/uml/definitions.adoc b/docs/modules/ROOT/pages/uml/definitions.adoc index f1fecb8..c704fe5 100644 --- a/docs/modules/ROOT/pages/uml/definitions.adoc +++ b/docs/modules/ROOT/pages/uml/definitions.adoc @@ -6,16 +6,16 @@ This documentation makes references to three closely related and overlapping dom [[sec:cm]] === Conceptual Model -A _conceptual model_ is a representation of a system that uses concepts to form said representation. A _concept_ can be viewed as an idea or notion; a unit of thought [xref:references.adoc#ref:skos-spec[skos-spec]]. A concept needs to be well named by providing as many understandable labels as necessary (for example, multiple different expressions or languages), supported by a clear definition with examples and explanatory notes. +A _conceptual model_ is a representation of a system that uses concepts to form said representation. A _concept_ can be viewed as an idea or notion; a unit of thought [xref:references.adoc#ref:skos-spec[skos-spec]] in the mind, which can be put into writing -- _realized_ as a representation -- in various forms (such as part of a diagram or mind map). A concept on paper needs to be well named by providing as many understandable labels as necessary (for example, multiple different expressions or languages), supported by a clear definition with examples and explanatory notes. -The conceptual model comprises representations of concepts, their qualities or attributes and relationships to other concepts. Most commonly these are association and generalisation relations. In addition, behaviour can be represented, ranging from the concept level up to the level of the system as a whole. Behavioural aspects, however, fall out of the scope in the current specification, which addresses at the structural elements mainly. +The conceptual model comprises representations of realized concepts, their qualities or attributes, and relationships to other concepts. Most commonly, these are _association_ and _generalisation_ relations. In addition, behaviour can be represented, ranging from the concept level up to the level of the system as a whole. Behavioural aspects, however, fall out of the scope of the current specification, which addresses only the structural elements. [[sec:uml]] === Unified Modelling Language (UML) -The _Unified Modelling Language (UML)_ is a general-purpose, developmental, modelling language in the field of software engineering that is intended to provide a standard way to visualise the design of a system [xref:references.adoc#ref:uml-userguide[uml-userguide]]. +The _Unified Modelling Language (UML)_ is a general-purpose, developmental, computer modelling language in the field of software engineering, that is intended to provide a standard way to visualise the design of a system [xref:references.adoc#ref:uml-userguide[uml-userguide]]. It is a language that facilitates the realization and visualization (diagramming) of a conceptual model, such as the eProcurement conceptual model, which represents the real-world subject matter of public procurement. -This set of specifications is based on the assumption that the conceptual models are represented with UML. Moreover, for the purposes of this convention only the structural elements of UML are considered, and in particular those comprising a class diagram. Next, the most important structural elements are introduced. +The set of specifications in this documentation is based on the assumption that the conceptual models are represented with UML. Moreover, for the purposes of the convention used, only the structural elements of UML are considered, in particular those comprising a class diagram. The most important structural elements are described below. A _class_ represents a discrete concept within the domain being modelled. It is a description of a set of individual objects that share the same attributes, behaviour, relationships. Graphically, a class is rendered as a rectangle [xref:references.adoc#ref:uml-userguide[uml-userguide]].