diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..21aee9e --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +doc/* linguist-documentation diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml new file mode 100644 index 0000000..783943d --- /dev/null +++ b/.github/workflows/unit-tests.yml @@ -0,0 +1,34 @@ +name: Tests + +on: + push: + branches: [ feature/* , main, hotfix/*, release/* ] +# pull_request: +# branches: [ main, release/* ] + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + build: + name: Build and Run Tests + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis + - name: Build and Run Tests + run: mvn install + - name: current dir + run: pwd + - name: current dir + run: ls -la ./target/surefire-reports + - name: Publish Test Report + uses: mikepenz/action-junit-report@v3 + if: success() || failure() # always run even if the previous step fails + with: + report_paths: '**/target/surefire-reports/test-*.xml' + detailed_summary: true + diff --git a/.gitignore b/.gitignore index de5c021..107927f 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,8 @@ __pycache__/ # Distribution / packaging .Python -build/ +/build/ +/node_modules/ develop-eggs/ dist/ downloads/ diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 0e9d047..2625766 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -7,6 +7,7 @@ Special thanks for all the people who had helped this project so far. * [Eugeniu Costetchi](eugen@meaningfy.ws) * [Dragos Paun](dragos.paun@meaningfy.ws) + ## Contributors * [Csongor Nyulas](csongor.nyulas@meaningfy.ws) diff --git a/CONTRIBUTORS.md.bak b/CONTRIBUTORS.md.bak new file mode 100644 index 0000000..0e9d047 --- /dev/null +++ b/CONTRIBUTORS.md.bak @@ -0,0 +1,13 @@ +# Contributors + +Special thanks for all the people who had helped this project so far. + +## Developers +* +* [Eugeniu Costetchi](eugen@meaningfy.ws) +* [Dragos Paun](dragos.paun@meaningfy.ws) + +## Contributors + +* [Csongor Nyulas](csongor.nyulas@meaningfy.ws) +* [Andreea-Nicoleta Pasare](andreea.pasare@meaningfy.ws) \ No newline at end of file diff --git a/README.md b/README.md index dd73bbe..4a26b03 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,90 @@ -# model2owl-docs +# model2owl -[Read online](https://meaningfy-ws.github.io/model2owl-docs/0.0.1/index.html) +This project comprises a set of tools for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal ontology. This transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in the documentation. -This repository covers the documentation for [model2owl project](https://github.com/OP-TED/model2owl). +* UML -> OWL 2 (light / complete) +* UML -> SHACL -model2owl if a set of tools for transforming UML (v2.5) model from its XMI (v2.5.1) serialisation into an OWL formal ontology, SHACl data shapes ad glossary. This transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in the documentation. +This work is developed in the context of [eProcurement ontology project](https://github.com/eprocurementontology/eprocurementontology) financed by the Digital Europe Programme and led by the [Publications Office of the European Union](https://op.europa.eu/en/). -# Contributing +### Documents +* The **architectural design** and the formal specifications are provided in the [Ontology architecture document](docs/ontology-architecture/ontology-architecture.pdf). +* The technical **conventions** for the UML representation of the conceptual model are provided in [UML conventions document](docs/uml-conventions/uml-conventions.pdf) +* An **inventory** of conformance tests derived from the UML conventions document are provided in the [Inventory Worksheet document](docs/checkers-inventory/eProcurement conceptual model checkers inventory.xlsx) +* The **transformation rules** from UML into OWL and SHACL are provided in the [uml2owl transformation document](docs/uml2owl-transformation/uml2owl-transformation.pdf) + +### Scripts +* [html-conventions-report.xsl](src/html-conventions-report.xsl) is the script checking the conformance to the technical conventions of the conceptual model. +* [owl-core.xsl](src/owl-core.xsl) is the transformation script for the core OWL ontology. +* [shacl-shapes.xsl](src/shacl-shapes.xsl) is the transformation script for the SHACL data shape constraints +* [owl-restrictions.xsl](src/owl-restrictions.xsl) is the transformation script for the restrictions of OWL ontology (on classes and properties). + +### Script unit tests + +* [test/unitTest/test-html-conventions-lib]( +https://github.com/meaningfy-ws/model2owl/tree/master/test/unitTests/test-html-conventions-lib) is the location of the unit tests for the script checking the conformance to the technical conventions of the conceptual model are +* [test/unitTest/test-owl-core-lib](https://github.com/meaningfy-ws/model2owl/tree/master/test/unitTests/test-owl-core-lib) is the location of the unit tests for the transformation script for the core OWL ontology. + +* [test/unitTest/test-shacl-shape-lib](https://github.com/meaningfy-ws/model2owl/tree/master/test/unitTests/test-shacl-shape-lib) is the location of the unit tests for the transformation script for the SHACL data shape constraints. +* [test/unitTest/reasoning-layer-lib](https://github.com/meaningfy-ws/model2owl/tree/master/test/unitTests/reasoning-layer-lib) is the location of the unit tests for the transformation script for the restrictions of OWL ontology (on classes and properties). + +## Running the transformation + +The scripts developed in this project conform to XSLT 3.0 and can be executed with a corresponding XSLT engine of choice. A recommendation is to use [Saxon-HE](http://saxon.sourceforge.net/), but it is not the only one. + +The input eProcurement conceptual model is available in the [eProcurement Ontology project on GitHub](https://github.com/eprocurementontology/eprocurementontology). Note that the XMI (v.2.5.1) output is generated with [Enterprise Architect](https://sparxsystems.com/products/ea/index.html) and was not tested with outputs from other software (although, XMI is an OMG standard). But, this does not restrict the current scripts to this project alone and any UML model that conforms to the specified UML conventions can be transformed into a formal ontology. + +We assume that the users of this project are familiar with XML, UML and XSLT technologies and know how to perform an XSLT transformation. + +## Automation with Makefile + +## Create an virtual environment +pip install virtualenv +virtualenv venv +## Activate your venv +source venv/bin/activate + +## Install rdflib inside your virtual environment +pip install rdflib +## Combine multiple XMI / XML UML documents +make merge-xmi + +This will merge multiple input XMI / XML UML documents into a single one. The output is located under ../output/combined-xmi/ and will be used to generate a single glossary. + +## Generate the glossary from the merged document +make generate-glossary +The glossary will generated and located in the ../output/glossary/ + +## Repository Structure + +* /src - source code of the XSLT scripts generating the HTML conventions report. + * /common , /html-conventions-lib, /reasoning-layer-lib and /shacl-shape-lib contain modules loaded by the main files. + * /static contains JS and CSS styles refereed by HTML reports. It should be copied to wherever the report is saved in order to ensure proper display. + * config-parameters.xsl - the configurations file that may be adjusted as necessary. + * html-conventions-report.xsl - source code of the XSLT scripts generating the HTML conventions report. + * owl-core.xsl - Transformation script for the core ontology + * shacl-shapes.xsl - Transformation script for the SHACL shapes + * owl-restrictions.xsl - Transformation script for the ontology intensional definitions based on the class and property restrictions + +* /test - contains unit tests for each XSL module ensuring the correct implementation. + * /test/unitTests - contain XSpec unit tests + * /test/testData - test data used in the unit tests + +# Contributing You are more than welcome to help expand and mature this project. When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. -Please note we adhere to [Apache code of conduct](https://www.apache.org/foundation/policies/conduct), please follow it in all your interactions with the project. +Please note we adhere to [Apache code of conduct](https://www.apache.org/foundation/policies/conduct), please follow it in all your interactions with the project. + +## Licence + +The documents, such as reports and specifications, available in the /doc folder, are licenced under a [CC BY 4.0 licence](https://creativecommons.org/licenses/by/4.0/deed.en). + +The XSLT (stylesheets) and other scripts are licenced under [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) licence. + -# Licence -The documents, such as reports and specifications are licenced under a [CC BY 4.0 licence](https://creativecommons.org/licenses/by/4.0/deed.en). -The source code and other scripts are licenced under [EUPL v1.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12) licence. diff --git a/config-proxy.xsl b/config-proxy.xsl new file mode 100644 index 0000000..ed92a2a --- /dev/null +++ b/config-proxy.xsl @@ -0,0 +1,24 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/antora.yml b/docs/antora.yml index e12b06c..004917a 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,6 +1,17 @@ name: ROOT -version: 0.0.1 -title: model2owl documentation +version: public-review +title: model2owl Documentation start_page: ROOT:index.adoc +asciidoc: + attributes: + imagesdir: images + xrefstyle: short@ + example-caption: Rule@ + example-refsig: Rulota + listing-caption: Listing@ + listing-refsig: Listing + table-refsig: Tabella + counter: rule-cnt@ nav: - modules/ROOT/nav.adoc + diff --git a/docs/modules/ROOT/images/f1.png b/docs/modules/ROOT/images/f1.png new file mode 100644 index 0000000..d01b188 Binary files /dev/null and b/docs/modules/ROOT/images/f1.png differ diff --git a/docs/modules/ROOT/images/f10.png b/docs/modules/ROOT/images/f10.png new file mode 100644 index 0000000..74da755 Binary files /dev/null and b/docs/modules/ROOT/images/f10.png differ diff --git a/docs/modules/ROOT/images/f11.png b/docs/modules/ROOT/images/f11.png new file mode 100644 index 0000000..5d8b1d3 Binary files /dev/null and b/docs/modules/ROOT/images/f11.png differ diff --git a/docs/modules/ROOT/images/f12.png b/docs/modules/ROOT/images/f12.png new file mode 100644 index 0000000..748a2c8 Binary files /dev/null and b/docs/modules/ROOT/images/f12.png differ diff --git a/docs/modules/ROOT/images/f13.png b/docs/modules/ROOT/images/f13.png new file mode 100644 index 0000000..bb0931e Binary files /dev/null and b/docs/modules/ROOT/images/f13.png differ diff --git a/docs/modules/ROOT/images/f14.png b/docs/modules/ROOT/images/f14.png new file mode 100644 index 0000000..7db5b3d Binary files /dev/null and b/docs/modules/ROOT/images/f14.png differ diff --git a/docs/modules/ROOT/images/f15.png b/docs/modules/ROOT/images/f15.png new file mode 100644 index 0000000..24ab187 Binary files /dev/null and b/docs/modules/ROOT/images/f15.png differ diff --git a/docs/modules/ROOT/images/f16.png b/docs/modules/ROOT/images/f16.png new file mode 100644 index 0000000..c0283b1 Binary files /dev/null and b/docs/modules/ROOT/images/f16.png differ diff --git a/docs/modules/ROOT/images/f17.png b/docs/modules/ROOT/images/f17.png new file mode 100644 index 0000000..71ee10e Binary files /dev/null and b/docs/modules/ROOT/images/f17.png differ diff --git a/docs/modules/ROOT/images/f18.png b/docs/modules/ROOT/images/f18.png new file mode 100644 index 0000000..267921f Binary files /dev/null and b/docs/modules/ROOT/images/f18.png differ diff --git a/docs/modules/ROOT/images/f19.png b/docs/modules/ROOT/images/f19.png new file mode 100644 index 0000000..98d0529 Binary files /dev/null and b/docs/modules/ROOT/images/f19.png differ diff --git a/docs/modules/ROOT/images/f2.png b/docs/modules/ROOT/images/f2.png new file mode 100644 index 0000000..0ae21e0 Binary files /dev/null and b/docs/modules/ROOT/images/f2.png differ diff --git a/docs/modules/ROOT/images/f3.png b/docs/modules/ROOT/images/f3.png new file mode 100644 index 0000000..eaf5742 Binary files /dev/null and b/docs/modules/ROOT/images/f3.png differ diff --git a/docs/modules/ROOT/images/f4.png b/docs/modules/ROOT/images/f4.png new file mode 100644 index 0000000..399b100 Binary files /dev/null and b/docs/modules/ROOT/images/f4.png differ diff --git a/docs/modules/ROOT/images/f5.png b/docs/modules/ROOT/images/f5.png new file mode 100644 index 0000000..8e35841 Binary files /dev/null and b/docs/modules/ROOT/images/f5.png differ diff --git a/docs/modules/ROOT/images/f6.png b/docs/modules/ROOT/images/f6.png new file mode 100644 index 0000000..1f5b37d Binary files /dev/null and b/docs/modules/ROOT/images/f6.png differ diff --git a/docs/modules/ROOT/images/f7.png b/docs/modules/ROOT/images/f7.png new file mode 100644 index 0000000..46968ac Binary files /dev/null and b/docs/modules/ROOT/images/f7.png differ diff --git a/docs/modules/ROOT/images/f8.png b/docs/modules/ROOT/images/f8.png new file mode 100644 index 0000000..b2b62dc Binary files /dev/null and b/docs/modules/ROOT/images/f8.png differ diff --git a/docs/modules/ROOT/images/f9.png b/docs/modules/ROOT/images/f9.png new file mode 100644 index 0000000..4d1408e Binary files /dev/null and b/docs/modules/ROOT/images/f9.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 624329b..3dc948f 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -12,7 +12,10 @@ ** xref:uml/conv-datatypes.adoc[uml:DataType] ** xref:uml/conv-packages.adoc[uml:Package] ** xref:uml/conv-connectors.adoc[UML Connector Elements] -// * xref:checkers/model2owl-checkers.adoc[UML convention checking rules] -* xref:attachment$ePO_UML_conceptual_model_checkers_inventory_V3.xlsx[UML convention checking rules] +* xref:checkers/model2owl-checkers.adoc[UML convention checking rules] * xref:transformation/uml2owl-transformation.adoc[Transformation Rules] +** xref:transformation/transf-rules1.adoc[Rules for UML Classes and Attributes] +** xref:transformation/transf-rules2.adoc[Rules for UML Connectors] +** xref:transformation/transf-rules3.adoc[Rules for UML Datatypes] +** xref:transformation/transf-rules4.adoc[Rules for UML Descriptors] * xref:references.adoc[References] diff --git a/docs/modules/ROOT/pages/epo-context.adoc b/docs/modules/ROOT/pages/epo-context.adoc index 66d67d0..66950a4 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 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. +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 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. diff --git a/docs/modules/ROOT/pages/transformation/tikz-grafoo.adoc b/docs/modules/ROOT/pages/transformation/tikz-grafoo.adoc new file mode 100644 index 0000000..56985b2 --- /dev/null +++ b/docs/modules/ROOT/pages/transformation/tikz-grafoo.adoc @@ -0,0 +1,213 @@ +//// +== Introduction + +Graffoo, a Graphical Framework for OWL Ontologiesfootnote:[https://essepuntato.it/graffoo/], is an open source tool that can be used to present the classes, properties and restrictions within OWL ontologies, or sub-sections of them, as clear and easy-to-understand diagrams. + +This library implements the Graffoo graphical notationfootnote:[https://essepuntato.it/graffoo/specification/] as a set of TikZ styles and macros for increased usability. You can use it to draw OWL ontology fragments or RDF graphs in general. The basic components of Graffoo allow one to create classes, datatypes, annotation, data and object properties, individuals and ontologies. + +== Usage + +Once you have downloaded and installed the `tikz-graffoo` package, using it is a piece of cake: + +`\usepackage{tikz-graffoo}` + +Drawing Graffoo diagrams in TikZ can be done either (a) by using the node and path styles or (b) by using the macros provided by this package. The latter is recommended for ease and clarity, but the former may be chosen to gain higher control. + +=== Macros + +The macros for drawing the basic Graffoo components are as follows. An example for each of these elements is depicted in Figure#fig:macros-elements[1]. + +* *generic entity* + +`\gEntity{TikZ parameters}{Id}{Content text}` +* *class* + +`\gClass{TikZ parameters}{Id}{Content text}` +* *class restriction* + +`\gGlassRestriction{TikZ parameters}{Id}{Content text}` +* *datatype* + +`\gDatatype{TikZ parameters}{Id}{Content text}` +* *datatype restriction* + +`\gDatatypeRestriction{TikZ parameters}{Id}{Content text}` +* *instance* + +`\gInstance{TikZ parameters}{position}{Id}{Content text}` + +The position parameter indicates where to situate the circle: `below`, `above`, `left` or `right` of the text. +* *literal value* + +`\gLiteral{TikZ parameters}{Id}{Content text}` +* *additional axioms* + +`\gAxiom{TikZ parameters}{Id}{Content text}` +* *prefix definitions* + +`\gPrefixes{TikZ parameters}{Id}{Content text}` + +The LaTeXcode for the Figure #fig:macros-elements[1] is the following. + +.... +\begin{tikzpicture} + \gClass{}{class}{a class}; + \gGlassRestriction{right=3em of class} + {class-restriction}{a class restriction}; + + \gDatatype{right=3em of class-restriction} + {datatype}{a datatype}; + + \gDatatypeRestriction{below=2em of datatype} + {datatype-restriction}{a datatype restriction}; + + \gLiteral{below=2em of class} + {literal}{\valueLang[en]{value}}; + + \gInstance{below=2em of class-restriction} + {left}{instance1}{an instance\\of a class}; + + \gPrefixes{below=6em of class-restriction} + {prefixes1}{ + skos: \url{http://www.w3.org/2004/02/skos/core\#}\\ + dct: \url{http://purl.org/dc/terms/}}; +\end{tikzpicture} +.... + +The macros for drawing the basic Graffoo connectors are as follows. An example for each of these connectors is depicted in Figure#fig:macros-connectors[2]. + +* *generic predicate* + +`\gPredicate{subject node}{object node}{predicate}` +* *object property* + +`\gObjectProperty{subject node}{object node}{predicate}` +* *data property* + +`\gDataProperty{subject node}{object node}{predicate}` +* *annotation property* + +`\gAnnotationProperty{subject node}{object node}{predicate}` +* *simple link* + +`\gLink{subject node}{object node}` + +The LaTeXcode for the Figure #fig:macros-connectors[2] is the following. + +.... +\begin{tikzpicture} + \gEntity{below=2em of literal}{s1}{ subject }; + \gEntity{right=12em of s1}{o1}{ object }; + \gPredicate{s1}{o1}{predicate}; + + \gClass{below=2em of s1}{s2}{ domain }; + \gClass{right=12em of s2}{o2}{ range }; + \gObjectProperty{s2}{o2}{object property}; + + \gClass{below=2em of s2}{s3}{ domain }; + \gDatatype{right=12em of s3}{o3}{ range }; + \gDataProperty{s3}{o3}{data property}; + + \gClass{below=2em of s3}{s4}{ domain }; + \gDatatype{right=12em of s4}{o4}{ range }; + \gAnnotationProperty{s4}{o4}{annotation property}; + + \gEntity{below=2em of s4}{s5}{ entity }; + \gAxiom{right=7em of s5}{o5}{these are some additional axioms\\ + on two lines, best expressed in Machester Syntax }; + \gLink{s5}{o5}; +\end{tikzpicture} +.... + +=== Styles + +By using TikZ styles provided by this library, the same effect can be achieved as in the case of employing the macros listed above. The styles corresponding to each Graffoo element that should be applied to TikZ nodes are as follows. + +* `entity` +* `class` +* `class-restriction` +* `datatype` +* `datatype-restriction` +* `literal` or `value` (they are equivalent) +* `instance-r`, `instance-l`, `instance-a`, `instance-r` +* `axiom` +* `pref` (should be applied to a node split into two parts) + +The styles corresponding to each Graffoo property type that should be applied to TikZ paths are as follows. + +* `predicate` +* `object-property` +* `data-property` +* `annotation-property` +* `link` + +An example of drawing the diagram content as in Figure #fig:macros-elements[1] and #fig:macros-connectors[2] using styles alone (no macros) is provided below. + +.... +\begin{tikzpicture} + \node[class] (class) {a class}; + + \node[class-restriction, right=2em of class] + (class-restriction) {a class restriction}; + + \node[datatype, right=2em of class-restriction] + (datatype) {a datatype}; + + \node[datatype-restriction, below=2em of datatype] + (datatype-restriction) {a datatype restriction}; + + \node[literal, below=2em of class] + (literal) { \valueLang[en]{value} }; + + \node[instance-l, below=2em of class-restriction] + (instance1) { an instance\\ of a class}; + + \node[entity, below=2em of literal] + (s1) { subject entity }; + \node[entity, right=12em of s1] + (o1) { object entity }; + \draw[predicate] (s1) -- (o1) + node[midway,fill=white,] {property}; + + \node[entity, below=2em of s1] + (s2) { subject entity }; + \node[entity, right=12em of s2] + (o2) { object entity }; + \draw[object-property] (s2) -- (o2) + node[midway,fill=white,] {object\\property}; + + \node[entity, below=2em of s2] + (s3) { subject entity }; + \node[entity, right=12em of s3] + (o3) { object entity }; + \draw[data-property] (s3) -- (o3) + node[midway,fill=white,] {data\\property}; + + \node[entity, below=2em of s3] + (s4) { subject entity }; + \node[entity, right=12em of s4] + (o4) { object entity }; + \draw[annotation-property] (s4) -- (o4) + node[midway,fill=white,] {annotation\\property}; + + \node[entity, below=2em of s4] + (s5) { subject entity }; + \node[entity, right=12em of s5] + (o5) { object entity }; + \draw[link] (s5) -- (o5); + + \node [pref, below=3em of s5.west, anchor=north west] + (prefix) {\textbf{\sffamily Prefixes:} + \nodepart{two} + skos: \url{http://www.w3.org/2004/02/skos/core#}\\ + dct: \url{http://purl.org/dc/terms/}}; +\end{tikzpicture} +.... + +=== Helpers + +Writing literal values using the Turtle or Manchester syntax is a little cumbersome. To make it easier we provide three macros. + +* *plain literal value* + +`\valuePlain{value}` generates +* *typed literal* + +`\valueTyped[datatype]{value}` generates + +`\valueTyped{value}` generates +* *language tagged literal* + +`\valueLang[lang]{value}` generates + +`\valueLang{value}` generates + +== License and contributions + +`tikz-graffoo` may be distributed and/or modified under the conditions of the LaTeX Project Public License version 1.3 or later. The Current Maintainer of this work is Eugeniu Costetchi (costezki.eugen@gmail.com), who welcomes contributions to the package on https://github.com/costezki/owl4latex[GitHub]. + +The goal of this library is to provide a toolkit to draw quickly and efficiently beautiful OWL diagrams. Building such a library can be challenging for one pair of hands alone. If you have used this library yourself or have seen it used, we would greatly appreciate your opinion and feedback . Please open a Github issue or privately email the Current Maintainer with as much information as you can. + +We also welcome technical feedback and bug reports in the form of GitHub Issues and pull requests. + +//// \ No newline at end of file diff --git a/docs/modules/ROOT/pages/transformation/transf-rules1.adoc b/docs/modules/ROOT/pages/transformation/transf-rules1.adoc new file mode 100644 index 0000000..337485b --- /dev/null +++ b/docs/modules/ROOT/pages/transformation/transf-rules1.adoc @@ -0,0 +1,676 @@ +[[sec:tran-rules]] +== Transformation of UML classes and attributes +:source-highlighter: pygments +:reftext: Transformation of UML classes and attributes + +In this section are specified transformation rules for UML class and attribute elements. <> provides an overview of the section coverage. + + +[[tab:class-attribute-overview]] +.Overview of transformation rules for UML classes and attributes +[cols="<,<,<,<",options="header",] +|=== +|UML element |Rules in core ontology layer |Rules in data shape layer |Rules in reasoning layer +|Class |<> |<> | +|Abstract class | |<> | +|Attribute |<> |<> |<> +|Attribute type | |<> |<> +|Attribute multiplicity | |<> |<>, <> +|=== + +[[sec:class]] +=== Class + +In UML, a Class is purposed to specify a classification of objects. UML represents atomic classes as named elements of type _Class_ without further features. In OWL, the atomic class, `owl:Class`, has no intention. It can only be interpreted by its name that has a meaning in the world outside the ontology. The atomic class is a class description that is simultaneously a class axiom . + +.Visual representation of a class in UML (on the left) and OWL (on the right) +[#fig:class-visual] +image::f6.png[6] + + +[#rule:class-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:C.01}. Class -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify an OWL Class declaration axiom for each UML Class, where the URI of the OWL class is deterministically generated from the UML Class name. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the core ontology layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the class at the time of its creation. + +[cols="a,a", options="noheader"] +|=== +| +.Class declaration in Turtle syntax +[source,Turtle] +---- +:ClassName a owl:Class ; +. +---- +| +.Class declaration in RDF/XML syntax +[source,XML] +---- + + +---- +|=== + +//WARNING: **TODO:** See if we want to add the `rdfs:label` here, or we just rely on this information being added at the time of processing the Element's descriptors, based on the lexicalization, as described in the xref:transformation/transf-rules4.adoc[Section on Transformation of UML descriptors]. + +//*Alternative layouts:* +//[IMPORTANT] +//[#rule:test1,caption='{example-caption} {rule-cnt}',title='{example-caption} {rule-cnt}: Class -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +//==== +// +//Specify declaration axiom for UML Class as OWL Class where the URI and a label are deterministically generated from the class name. The label and, if available, the description are ascribed to the class. +// +//`[IMPORTANT]` +//==== +// +//[#rule:test2,caption=Rule,title='{example-caption} {rule-cnt}: Class -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +//**** +//Specify declaration axiom for UML Class as SHACL Node Shape where the URI and a label are deterministically generated from the class name. +// +//`[sidebar]` +//**** +// + + +[#rule:class-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Class -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a SHACL NodeShape declaration axiom for each UML Class. The URIs of the node shape and of the OWL class they refer to, are deterministically generated from the UML Class name. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the data shape layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the node shape at the time of its creation. + +[cols="a,a", options="noheader"] +|=== +| +.Node shape declaration in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName a sh:NodeShape ; + sh:targetClass :ClassName ; +. +---- +| +.Node shape declaration in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + + +[[sec:class-abstract]] +=== Abstract class + +In UML, an abstract Class cannot have any instances and only its subclasses can be instantiated. The abstract classes are declared just like the regular ones (<> and <>) and in addition a constraint validation rule is generated to ensure that no instance of this class is permitted. + +OWL follows the Open World Assumption , therefore, even if the ontology does not contain any instances for a specific class, it is unknown whether the class has any instances. We cannot confirm that the UML abstract class is correctly defined with respect to the OWL domain ontology, but we can detect if it is not using SHACL constraints. + +.Visual representation of an abstract class in UML (on the left) and OWL (on the right) +[#fig:class-abstract-visual] +image::f7.png[7] + + +[#rule:class-abstract-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Abstract class -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a SHACL NodeShape declaration axiom for each abstract UML Class, with a SPARQL constraint that selects all instances of this class. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the data shape layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the node shape at the time of its creation. + +[cols="a,a", options="noheader"] +|=== +| +.Instance checking constraint in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName a sh:NodeShape ; + sh:targetClass :ClassName ; + sh:sparql [ + sh:select """SELECT $this + WHERE { + $this a :ClassName . + } + """ ; + ] ; +. +---- +| +.Instance checking constraint in RDF/XML syntax +[source,XML] +---- + + + + SELECT $this + WHERE { + $this a :ClassName . + } + + + +---- +|=== + + +[[sec:attribute]] +=== Attribute + +The UML attributes are properties that are owned by a Classifier, e.g. Class. Both UML attributes and associations are represented by one meta-model element – Property. OWL also allows one to define properties. A transformation of UML attribute to OWL data property or OWL object property bases on its type. If the type of the attribute is a primitive type it should be transformed into OWL data property. However, if the type of the attribute is a structured datatype, class of enumeration, it should be transformed into an OWL object property. + +.Visual representation of class attributes in UML (on the left) and OWL properties (on the right) +[#fig:attribute-visual] +image::f8.png[8] + + +[#rule:attribute-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify declaration axiom(s) for attribute(s) of a UML Class as OWL data or object properties, deciding based on their types. The attributes with primary types should be treated as data properties, whereas those typed with classes or enumerations should be treated as object properties. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the core ontology layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the property at the time of its creation. + +[cols="a,a", options="noheader"] +|=== +| +.Data property declaration in Turtle syntax +[source,Turtle] +---- +:attribute1 a owl:DatatypeProperty ; +. +---- +| +.Data property declaration in RDF/XML syntax +[source,XML] +---- + + +---- + +| +.Object property declaration in Turtle syntax +[source,Turtle] +---- +:attribute2 a owl:ObjectProperty ; +. +---- +| +.Object property declaration in RDF/XML syntax +[source,XML] +---- + + +---- +|=== + +//WARNING: **TODO:** See if we want to add the `rdfs:label` and `skos:definition` here, or we just rely on this information being added at the time of processing the Element's descriptors, based on the lexicalization, as described in the xref:transformation/transf-rules4.adoc[Section on Transformation of UML descriptors]. + + +=== Attribute owner + +[#rule:attribute-rc-domain,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute domain -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify data (or object) property domains for attribute(s). +==== + +[cols="a,a", options="noheader"] +|=== +| +.Data property domain specification in Turtle syntax +[source,Turtle] +---- +:attribute1 a owl:DatatypeProperty ; + rdfs:domain :ClassName ; +. +---- +| +.Data property domain specification in RDF/XML syntax +[source,XML] +---- + + + +---- + +| +.Object property domain specification in Turtle syntax +[source,Turtle] +---- +:attribute2 a owl:ObjectProperty ; + rdfs:domain :ClassName ; +. +---- +| +.Object property domain specification in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +[#rule:attribute-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Class attribute -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a SHACL PropertyShape declaration axiom for each attribute. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the core ontology layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the property shape at the time of its creation. + +[cols="a,a", options="noheader"] +|=== +| +.PropertyShape declaration for attributes in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName + sh:property shape:ClassName-attributeName ; +. +shape:ClassName-attributeName a sh:PropertyShape ; + sh:path :attributeName ; +. +---- +| +.PropertyShape declaration for attributes in RDF/XML syntax +[source,XML] +---- + + + + + + + +---- +|=== + + +=== Attribute type + +[#rule:attribute-rc-range,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute type -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify data (or object) property range for attribute(s). +==== + +[cols="a,a", options="noheader"] +|=== +| +.Data property range specification in Turtle syntax +[source,Turtle] +---- +:attribute1 a owl:DatatypeProperty; + rdfs:range xsd:string; +. +---- +| +.Data property range specification in RDF/XML syntax +[source,XML] +---- + + + +---- + +| +.Object property range specification in Turtle syntax +[source,Turtle] +---- +:attribute2 a owl:ObjectProperty; + rdfs:range :OtherClass; +. +---- +| +.Object property range specification in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +[#rule:attribute-ds-range,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute type -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Within the SHACL PropertyShape corresponding to an attribute of a UML Class, specify property constraints indicating the range class or datatype. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Property datatype constraint in Turtle syntax +[source,Turtle] +---- +# @prefix : . +@prefix shape: . +@prefix sh: . +@prefix xsd: . + +shape:ClassName-attribute1 + sh:datatype xsd:string ; +. +---- +| +.Property datatype constraint in RDF/XML syntax +[source,XML] +---- + + + +---- + +| +.Property class constraint in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName-attribute2 + sh:class :OtherClass ; +. +---- +| +.Property class constraint in RDF/XML syntax +[source,XML] +---- + + + + +---- +|=== + +[[sec:attribute-multiplicity]] +=== Attribute multiplicity + +In , multiplicity bounds of multiplicity element are specified in the form of `[ .. ]`. The lower-bound, also referred here as minimum cardinality or `min` is of a non-negative Integer type and the upper-bound, also referred here as maximum cardinality or `max`, is of an UnlimitedNatural type (see Section xref:transformation/transf-rules3.adoc#sec:primitive-type[Primitive datatype]). The strictly compliant specification of UML in version 2.5 defines only a single value range for MultiplicityElement. not limit oneself to a single interval. Therefore, the below UML to OWL mapping covers a wider case – a possibility of specifying more value ranges for a multiplicity element. Nevertheless, if the reader would like to strictly follow the current UML specification, the particular single lower..upper bound interval is therein also comprised. + + +.Visual representation of class attributes with multiplicity in UML (on the left) and OWL class specialising an anonymous restriction of properties (on the right) +[#fig:attribute-multiplicity-visual] +image::f9.png[9] + + +It should be noted that upper-bound of UML MultiplicityElement can be specified as unlimited: ``*''. In OWL, cardinality expressions serve to restrict the number of individuals that are connected by an object property expression to a given number of instances of a specified class expression . Therefore, UML unlimited upper-bound does not add any information to OWL ontology, hence it is not transformed. + +[#rule:attribute-rc-multiplicity,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute multiplicity -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +For each attribute multiplicity of the form ( min .. max ), where min and max are different than ``*'' (any), specify a subclass axiom where the OWL class, corresponding to the UML Class, specialises an anonymous restriction of properties formulated according to the following cases. + +. exact cardinality, e.g. [2..2] +. minimum cardinality only, e.g. [1..*] +. maximum cardinality only, e.g. [*..2] +. maximum and maximum cardinality , e.g. [1..2] +==== + +[cols="a,a", options="noheader"] +|=== +| +.Exact cardinality constraint in Turtle syntax +[source,Turtle] +---- +:ClassName + rdfs:subClassOf [ a owl:Restriction ; + owl:cardinality "2"^^xsd:integer; + owl:onProperty :attribute1 ; + ] ; +. +---- +| +.Exact cardinality constraint in RDF/XML syntax +[source,XML] +---- + + + + + 2 + + + +---- + +| +.Min cardinality constraint in Turtle syntax +[source,Turtle] +---- +:ClassName + rdfs:subClassOf [ a owl:Restriction ; + owl:minCardinality "1"^^xsd:integer; + owl:onProperty :attribute2 ; + ] ; +. +---- +| +.Min cardinality constraint in RDF/XML syntax +[source,XML] +---- + + + + + 1 + + + +---- + +| +.Max cardinality constraint in Turtle syntax +[source,Turtle] +---- +:ClassName + rdfs:subClassOf [ a owl:Restriction ; + owl:maxCardinality "2"^^xsd:integer; + owl:onProperty :attribute3 ; + ] ; +. +---- +| +.Max cardinality constraint in RDF/XML syntax +[source,XML] +---- + + + + + 2 + + + +---- + +| +.Min and max cardinality constraint in Turtle syntax +[source,Turtle] +---- +:ClassName + rdfs:subClassOf [ + rdf:type owl:Class ; + owl:intersectionOf ( + [ a owl:Restriction ; + owl:minCardinality "1"^^xsd:integer; + owl:onProperty :attribute4; ] + [ a owl:Restriction ; + owl:maxCardinality "2"^^xsd:integer; + owl:onProperty :attribute4; ] + ) ; + ] ; +. +---- +| +.Min and max cardinality constraint in RDF/XML syntax +[source,XML] +---- + + + + + + + 1 + + + + 2 + + + + + +---- +|=== + +Attributes with multiplicity exactly one correspond to functional object or data properties in OWL. If we apply the previous rule specifying min and max cardinality will lead to inconsistent ontology. To avoid that it is important that min and max cardinality are not generated from [1..1] multiplicity but only functional property axiom. + +[#rule:attribute-rc-multiplicity-one,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute multiplicity "one" -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +For each attribute that has multiplicity exactly one, i.e. [1..1], specify a functional property axiom. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Declaring a functional property in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix owl: . + +:attribute5 a owl:FunctionalProperty . +---- +| +.Declaring a functional property in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +[#rule:attribute-ds-multiplicity,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Attribute range shape -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Within the SHACL PropertyShape corresponding to an attribute of a UML Class, specify property constraints indicating the minimum and maximum cardinality, only where min and max are different from ``*'' (any) and multiplicity is not [1..1]. The expressions are formulated according to the following cases. + +. exact cardinality, e.g. [2..2] +. minimum cardinality only, e.g. [1..*] +. maximum cardinality only, e.g. [*..2] +. minimum and maximum cardinality , e.g. [1..2] +==== + +[cols="a,a", options="noheader"] +|=== +| +.Exact cardinality constraint in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-attribute1 + sh:minCount 2 ; + sh:maxCount 2 ; +. +---- +| +.Exact cardinality constraint in RDF/XML syntax +[source,XML] +---- + + 2 + 2 + +---- + +| +.Min cardinality constraint in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-attribute2 + sh:minCount 1 ; +. +---- +| +.Min cardinality constraint in RDF/XML syntax +[source,XML] +---- + + 1 + +---- + +| +.Max cardinality constraint in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-attribute3 + sh:maxCount 2 ; +. +---- +| +.Max cardinality constraint in RDF/XML syntax +[source,XML] +---- + + 2 + +---- + +| +.Min and max cardinality constraint in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-attribute4 + sh:minCount 1 ; + sh:maxCount 2 ; +. +---- +| +.Min and max cardinality constraint in RDF/XML syntax +[source,XML] +---- + + 1 + 2 + +---- +|=== diff --git a/docs/modules/ROOT/pages/transformation/transf-rules2.adoc b/docs/modules/ROOT/pages/transformation/transf-rules2.adoc new file mode 100644 index 0000000..be08113 --- /dev/null +++ b/docs/modules/ROOT/pages/transformation/transf-rules2.adoc @@ -0,0 +1,601 @@ +[[sec:tran-rules2]] +== Transformation of UML connectors + +In this section are specified transformation rules for UML association, generalisation and dependency connectors. <> provides an overview of the section coverage. + +[[tab:connectors-overview]] +.Transformation rules overview for UML connectors +[cols="<,<,<,<",options="header",] +|=== +|UML element |Rules in core ontology layer |Rules in data shape layer |Rules in reasoning layer +|Association |<> |<> | +|Association domain | | |<> +|Association range | |<> |<> +|Association multiplicity | |<> |<>, <> +|Association asymmetry | |<> |<> +|Association inverse | | |<> +|Dependency |<> |<> | +|Dependency domain | | |<> +|Dependency range | |<> |<> +|Dependency multiplicity | |<> |<>, <> +|Class generalisation |<> | | +|Property generalisation |<> | | +|Class equivalence | | |<> +|Property equivalence | | |<> +|=== + +[[sec:association-uni]] +=== Unidirectional association + +A binary Association specifies a semantic relationship between two member ends represented by properties. Please note that in accordance with specification , the association end names are not obligatory. However, we adhere to the UML conventions , where specification of at one member ends, for unidirectional association, and two member ends, for bidirectional association, is mandatory. Moreover, provision of a connector (general) name is discouraged. + +.Visual representation of a UML unidirectional association (on the left) and an OWL property with cardinality restriction on domain class (on the right) +[#fig:association-uni-visual] +image::f10.png[10] + + +[#rule:association-uni-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:R.01}. Unidirectional association -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify object property declaration axiom for the target end of the association/dependency. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the core ontology layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the property at the time of its creation. + +[cols="a,a", options="noheader"] +|=== +| +.Property declaration in Turtle syntax +[source,Turtle] +---- +:relationName a owl:ObjectProperty ; +. +---- +| +.Property declaration in RDF/XML syntax +[source,XML] +---- + + +---- +|=== + +//WARNING: **TODO:** See if we want to add the `rdfs:label` and `skos:definition` here, or we just rely on this information being added at the time of processing the Element's descriptors, based on the lexicalization, as described in the xref:transformation/transf-rules4.adoc[Section on Transformation of UML descriptors]. +// + +[#rule:association-uni-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:1.1}. Unidirectional association -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify PropertyShape declaration axiom for each association/dependency. +==== + +[TIP] +Ideally, in the implementation, this rule would be combined with the relevant rules (those for the data shape layer) in the xref:transformation/transf-rules4.adoc[Transformation of UML descriptors] section, to provide labels and documentation for the property shape at the time of its creation. + +[NOTE] +For handling bidirectional associations refer to the <> section. + +[cols="a,a", options="noheader"] +|=== +| +.PropertyShape declaration for associations in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName + sh:property shape:ClassName-relationName ; +. +shape:ClassName-relationName a sh:PropertyShape ; + sh:path :relationName ; +. +---- +| +.PropertyShape declaration for associations in RDF/XML syntax +[source,XML] +---- + + + + + + + +---- +|=== + + +=== Association source + + +[#rule:association-uni-domain-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association source -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify object property domain for the target end of the association/dependency. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Domain specification in Turtle syntax +[source,Turtle] +---- +:relationName a owl:ObjectProperty ; + rdfs:domain :ClassName ; +. +---- +| +.Domain specification in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +=== Association target + + +[#rule:association-uni-range-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association target -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify object property range for the target end of the association. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Range specification in Turtle syntax +[source,Turtle] +---- +:relationName a owl:ObjectProperty ; + rdfs:range :ClassName ; +. +---- +| +.Range specification in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + + +[#rule:association-uni-range-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association range shape -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Within the SHACL PropertyShape corresponding to an association relation linked to a given source UML Class, specify property constraints indicating the range class. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Property class constraint in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName-relationName + sh:class :OtherClass ; +. +---- +| +.Property class constraint in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +=== Association multiplicity + + +[#rule:association-uni-multiplicity-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association multiplicity -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +For the association/dependency target multiplicity, where min and max are different than ``*'' (any) and multiplicity is not [1..1], specify a subclass axiom where the source class specialises an anonymous restriction of properties formulated according to cases provided by xref:transformation/transf-rules1.adoc#rule:attribute-rc-multiplicity[rule:attribute-rc-multiplicity]. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Min cardinality restriction in Turtle syntax +[source,Turtle] +---- +:ClassName a owl:Class ; + rdfs:subClassOf [ a owl:Restriction ; + owl:minCardinality "1"^^xsd:integer; + owl:onProperty :relationName ; + ] ; +. +---- +| +.Min cardinality restriction in RDF/XML syntax +[source,XML] +---- + + + + + 1 + + + +---- +|=== + +[#rule:association-uni-multiplicity-one-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association multiplicity "one" -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +If the association/dependency multiplicity is exactly one, i.e. [1..1], specify a functional property axiom like in xref:transformation/transf-rules1.adoc#rule:attribute-rc-multiplicity-one[rule:attribute-rc-multiplicity-one]. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Declaring a functional property in Turtle syntax +[source,Turtle] +---- +:relationName a owl:FunctionalProperty . +---- +| +.Declaring a functional property in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +[#rule:association-uni-multiplicity-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association multiplicity -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Within the SHACL PropertyShape corresponding to an association/dependency relation linked to a given source UML Class, specify property constraints indicating minimum and maximum cardinality, according to cases provided by xref:transformation/transf-rules1.adoc#rule:attribute-ds-multiplicity[rule:attribute-ds-multiplicity]. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Min cardinality constraint in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-relationName + sh:minCount 1 ; +. +---- +| +.Min cardinality constraint in RDF/XML syntax +[source,XML] +---- + + 1 + +---- +|=== + +[[sec:association-self]] +=== Recursive association + +In case of recursive associations, that are from one class to itself, (depicted in <>), the transformation rules must be applied as in the case of regular unidirectional association, which are from <> to <>. In addition, the association must be marked as asymmetric expressed in <> and <>. + +.Visual representation of a UML recursive association (on the left) and OWL recursive properties with cardinality restrictions on domain class (on the right) +[#fig:association-self-visual] +image::f11.png[11] + +[#rule:association-uni-asymetry-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association asymmetry -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify an asymmetric object property axiom for each end of a recursive association. +==== + +[cols="a,a", options="noheader"] +|=== +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Declaring an asymmetric property in Turtle syntax +[source,Turtle] +---- +:relatesTo a owl:AsymmetricProperty . +---- +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Declaring an asymmetric property in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +[#rule:association-uni-asymetry-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association asymmetry -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Within the SHACL Node Shape corresponding to the UML Class, specify SPARQL constraint selecting instances connected by the object property in a reciprocal manner. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Declaring an asymmetric property in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName + sh:sparql [ + sh:select """ + SELECT ?this ?that + WHERE { + ?this :relatesTo ?that . + ?that :relatesTo ?this . + }""" ; ] ; +. +---- +| +.Declaring an asymmetric property in RDF/XML syntax +[source,XML] +---- + + + + SELECT ?this ?that + WHERE { + ?this :relatesTo ?that . + ?that :relatesTo ?this .} + + + +---- +|=== + +[[sec:association-bi]] +=== Bidirectional association + +The bidirectional associations should be treated, both on source and target ends, like two unidirectional associations (see <>). The transformation rules from <> and <>, and all the other rules for unidirectional associations shown in <> must be applied to both ends. In addition to those rules, the inverse relation axiom must be specified. + +.Visual representation of a UML bidirectional association (on the left) and OWL properties with cardinality restrictions on domain class (on the right) +[#fig:association-bi-visual] +image::f12.png[12] + + +[#rule:association-bi-inverse-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Association inverse -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify an inverse object property axiom between the source and target ends of the bidirectional association. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Declaring an inverse property in Turtle syntax +[source,Turtle] +---- +:relatesTo owl:inverseOf :isRelatedTo . +---- +| +.Declaring an inverse property in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +[[sec:dependecy]] +=== Unidirectional dependency + +In general the UML dependency connectors should be transformed by the rules specified for UML association connectors (see <>). + +The following two rules, concerning the transformation of dependency targets, are different from the rules for the transformation of association targets. + +[#rule:dependency-uni-range-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Dependency target -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify object property range for the target end of the dependency. +==== + +[cols="a,a", options="noheader"] +|=== +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Range specification in Turtle syntax +[source,Turtle] +---- +:relationName a owl:ObjectProperty ; + rdfs:range skos:Concept ; + . + +---- +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Range specification in RDF/XML syntax +[source,XML] +---- + + + + +---- +|=== + +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. + +[#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}'] +==== +Within the SHACL PropertyShape corresponding to a dependency relation linked to a given source UML Class, specify property constraints indicating the range class. +==== + +WARNING: **TODO:** Check these transformation rule examples and see if they make sense. It doesn't seem to. + +[cols="a,a", options="noheader"] +|=== +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Property class constraint in Turtle syntax +[source,Turtle] +---- +@prefix : . +@prefix shape: . +@prefix sh: . + +shape:ClassName-relationName + sh:class :EnumerationName ; +. +---- +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Property class constraint in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + + +[[sec:generalisation]] +=== Class generalisation + +Generalisation defines specialization relationship between Classifiers. In case of UML Classes it relates a more specific Class to a more general Class. + +.Visual representation of UML generalisation (on the left) and OWL subclass relation (on the right) +[#fig:generalisation-visual] +image::f13.png[13] + +//TODO: Verify this statement. It doesn't make too much sense. Needs reformulation. Plus, it might be irrelevant if we don't make a rule for generating (optional) disjoint classes statements +UML generalisation set groups generalisations; incomplete and disjoint constraints indicate that the set is not complete and its specific Classes have no common instances. The UML conventions specify that all sibling classes are by default disjoint, therefore even if no generalisation set is provided it is assumed to be implicit. + +[#rule:generalisation-class-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Class generalisation -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify subclass axiom for the generalisation between UML Classes. Sibling classes must be disjoint with one another. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Subclass declaration in Turtle syntax +[source,Turtle] +---- +:ClassName rdfs:subClassOf :SuperClass. +:OtherClass rdfs:subClassOf :SuperClass; + owl:disjointWith :ClassName ; +. +---- +| +.Subclass declaration in RDF/XML syntax +[source,XML] +---- + + + + + + + +---- +|=== + +=== Property generalisation + +Generalization defines specialization relationship between Classifiers. In case of the UML associations it relates a more specific Association to more general Association. + +.Visual representation of UML property generalisation (on the left) and OWL sub-property relation (on the right) +[#fig:generalisation-rel-visual] +image::f14.png[14] + + +[#rule:generalisation-property-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Property generalisation -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify sub-property axiom for the generalisation between UML association/dependency connectors. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Property specialisation in Turtle syntax +[source,Turtle] +---- +:hasSister rdfs:subPropertyOf :relatesTo . +:isSisterOf rdfs:subPropertyOf :isRelatedTo . +---- +| +.Property specialisation in RDF/XML syntax +[source,XML] +---- + + + + + + +---- +|=== + +=== Class equivalence + +.Visual representation of UML class equivalence (on the left) and OWL class equivalence (on the right) +[#fig:generalisation-equivalence-visual] +image::f15.png[15] + + +[#rule:equivalent-classes-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Equivalent classes -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify equivalent class axiom for the generalisation with `\<>` or `\<>` stereotype between UML Classes. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Class equivalence in Turtle syntax +[source,Turtle] +---- +:ClassName owl:equivalentClass :SuperClass. +---- +| +.Class equivalence in RDF/XML syntax +[source,XML] +---- + + + +---- +|=== + +=== Property equivalence + +[#rule:equivalent-properties-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:2.1}. Equivalent properties -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify equivalent property axiom for the generalisation with `\<>` or `\<>` stereotype between UML properties. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Property equivalence in Turtle syntax +[source,Turtle] +---- +:hasSister owl:equivalentProperty :relatesTo . +:isSisterOf owl:equivalentProperty :isRelatedTo . +---- +| +.Property equivalence in RDF/XML syntax +[source,XML] +---- + + + + + + +---- +|=== + + diff --git a/docs/modules/ROOT/pages/transformation/transf-rules3.adoc b/docs/modules/ROOT/pages/transformation/transf-rules3.adoc new file mode 100644 index 0000000..e06c6eb --- /dev/null +++ b/docs/modules/ROOT/pages/transformation/transf-rules3.adoc @@ -0,0 +1,257 @@ +[[sec:tran-rules3]] +== Transformation of UML datatypes + +In this section are specified transformation rules for UML datatypes and enumerations. <> provides an overview of the section coverage. + +[[tab:datatype-overview]] +.Overview of transformation rules for UML datatypes +[cols="<,<,<,<",options="header",] +|=== +|UML element |Rules in core ontology layer |Rules in data shape layer |Rules in reasoning layer +|Primitive datatype |<> | | +|Structured datatype |<> | | +|Enumeration |<> | |<> +|Enumeration item |<> | | +|=== + +[[sec:primitive-type]] +=== Primitive datatype + +The UML primitive type defines a predefined datatype without any substructure. The UML specification predefines five primitive types: String, Integer, Boolean, UnlimitedNatural and Real. Here we extended those to the list provided in <>. + + +.Visual representation of a UML Datatype (on the left) and an OWL Datatype (on the right) +[#fig:datatype-visual] +image::f16.png[16] + + +[#rule:datatype-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D.01}. Datatype -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify datatype declaration axiom for UML datatype as follows: + +* UML primitive datatypes are declared as the mapped XSD datatype in <>. +* XSD and RDF(S) datatypes are declared as such. +* Model specific datatypes are declared as such. +==== + +[[tab:type-mapping]] +.Mapping of UML primitive types to XSD datatypes +[cols="<,<",options="header",] +|=== +|UML datatype |XSD datatype +|Boolean |xsd:boolean +|Float |xsd:float +|Integer |xsd:integer +|Char |xsd:string +|String |xsd:string +|Short |xsd:short +|Long |xsd:long +|Decimal |xsd:decimal +|Real |xsd:float +|Date |xsd:date +|Numeric |xsd:integer +|Text |xsd:string +|=== + +[cols="a,a", options="noheader"] +|=== +| +.UML primitive datatype declaration in Turtle syntax +[source,Turtle] +---- +xsd:string a rdfs:Datatype ; + rdfs:label "String"@en ; + skos:definition "Description of the datatype meaning"@en ; +. +---- +| +.UML primitive datatype declaration in RDF/XML syntax +[source,XML] +---- + + String + Description of the datatype meaning + +---- + +| +//TODO: Should we change the rdfs:label to xsd:boolean? Is this, in fact, an example of XSD and RDF(S) (re-)declaration, +// or just another example of UML primitive datatype declaration? If yes, is this necessary at all? +.XSD and RDF(S) datatype declaration in Turtle syntax +[source,Turtle] +---- +xsd:boolean a rdfs:Datatype ; + rdfs:label "Boolean"@en ; + skos:definition "Description of the datatype meaning"@en ; +. +---- +| +.XSD and RDF(S) datatype declaration in RDF/XML syntax +[source,XML] +---- + + Boolean + Description of the datatype meaning + +---- + +| +.Model specific datatype declaration in Turtle syntax +[source,Turtle] +---- +:DatatypeName a rdfs:Datatype ; + rdfs:label "Datatype name"@en ; + skos:definition "Description of the datatype meaning"@en ; +. +---- +| +.Model specific datatype declaration in RDF/XML syntax +[source,XML] +---- + + Datatype name + Description of the datatype meaning + +---- +|=== + +=== Structured datatypes + +The UML structured datatype has attributes and is used to define complex data types. The structured datatypes should be treated as classes. + +[#rule:datatype-structured-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D01}. Structured Datatype -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify OWL class declaration axiom for UML structured datatype. +==== + +See applicable rules in Section on xref:transformation/transf-rules1.adoc#sec:class[Class Rules]. + +=== Enumeration + +UML Enumerations are kinds of datatypes, whose values correspond to one of user-defined literals. They should be transformed into SKOS concept schemes comprising the concepts corresponding to enumerated items. + + +.Visual representation of a UML Enumeration +[#fig:enumeration-uml-visual] +image::f17.png[17] + +.Visual representation of a SKOS concept scheme with concepts +[#fig:enumeration-owl-visual] +image::f18.png[18] + + +[#rule:enumeration-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D01}. Enumeration -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify SKOS concept scheme instantiation axiom for a UML enumeration. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Concept scheme instantiation in Turtle syntax +[source,Turtle] +---- +:EnumerationName a skos:ConceptScheme ; + rdfs:label "Controlled list" ; + skos:prefLabel "Controlled list"@en ; + skos:definition "Definition of the concept scheme meaning"@en ; +. +---- +| +.Concept scheme instantiation in RDF/XML syntax +[source,XML] +---- + + Controlled list + Controlled list + Definition of the concept scheme meaning + +---- +|=== + +[#rule:enumeration-rc,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D01}. Enumeration -- in reasoning layer',reftext='{example-caption} {rule-cnt}'] +==== +For a UML enumeration, specify an equivalent class restriction covering the set of individuals that are `skos:inScheme` of this enumeration. +==== + +[cols="a,a", options="noheader"] +|=== +| +.In-scheme equivalent class in Turtle syntax +[source,Turtle] +---- +@prefix skos: . +:EnumerationName a owl:Class ; + owl:equivalentClass [ + rdf:type owl:Restriction ; + owl:allValuesFrom :EnumerationName ; + owl:onProperty skos:inScheme ; + ] ; + rdfs:subClassOf skos:Concept; +. +---- +| +.In-scheme equivalent class in RDF/XML syntax +[source,XML] +---- + + + + + + + + + +---- +|=== + +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. +==== + +[cols="a,a", options="noheader"] +|=== +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Concept scheme instantiation in Turtle syntax +[source,Turtle] +---- +:itemA a skos:Concept ; + skos:inScheme :EnumerationName ; + rdfs:label "Item A" ; + skos:prefLabel "Item A"@en ; + skos:definition "Description fo the concept meaning"@en ; +. + +:itemB a skos:Concept ; + skos:inScheme :EnumerationName ; + rdfs:label "Item B" ; + skos:prefLabel "Item B"@en ; + skos:definition "Description fo the concept meaning"@en ; +. +---- +| +//TODO: Check if it's OK to use the same caption as for the previous rule +.Concept scheme instantiation in RDF/XML syntax +[source,XML] +---- + + + Item A + Item A + Description fo the concept meaning + + + + + Item B + Item B + Description fo the concept meaning + +---- +|=== diff --git a/docs/modules/ROOT/pages/transformation/transf-rules4.adoc b/docs/modules/ROOT/pages/transformation/transf-rules4.adoc new file mode 100644 index 0000000..546b74a --- /dev/null +++ b/docs/modules/ROOT/pages/transformation/transf-rules4.adoc @@ -0,0 +1,264 @@ +[[sec:tran-rules4]] +== Transformation of UML descriptors + +In this section are specified transformation rules for UML descriptive elements. <> provides an overview of the section coverage. + +[[tab:descriptiors-overview]] +.Overview of transformation rules for UML descriptors +[cols="<,<,<,<",options="header",] +|=== +|UML element |Rules in core ontology layer |Rules in data shape layer |Rules in reasoning layer +|Name |<> |<> | +|Note |<> |<> | +|Comment |<> |<> | +|=== + +=== Name + +Most of the UML elements are named. The UML conventions dedicate an extensive section to the naming conventions and how to deterministically generate a URI and a label from the UML element name. By default, we recommend the use of the SKOS lexicalization (`skos:prefLabel`) in the core ontology layer. In the future, this could be controlled by a flag in the configuration of the transformation tool. With such a flag one could enable RDFS lexicalization (`rdfs:label`) instead of, or in addition to, the SKOS lexicalization. + +[#rule:element-label-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:T.01}. Label -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a label for UML element. *TODO:* Update +==== + +[cols="a,a", options="noheader"] +|=== +| +.Labels in Turtle syntax +[source,Turtle] +---- +:ResourceName + skos:prefLabel "Resource name"@en ; +. +---- +| +.Labels in RDF/XML syntax +[source,XML] +---- + + Resource name + +---- +|=== + + +[#rule:element-label-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:T.01}. Label -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a label for UML element. *TODO:* Update +==== + +[cols="a,a", options="noheader"] +|=== +| +.Label declaration for NodeShape in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix rdfs: . + +shape:ClassName + rdfs:label "Class name" ; +. +---- +| +.Label declaration for NodeShape in RDF/XML syntax +[source,XML] +---- + + Class name + +---- + +| +.Label declaration for PropertyShape in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-PropertyName + sh:name "Property name" ; +. +---- +| +.Label declaration for PropertyShape in RDF/XML syntax +[source,XML] +---- + + Property name + +---- +|=== + +=== Note + +Most of the UML element foresee provisions of descriptions and notes. They should be transformed into `rdfs:comment` and `skos:definition`. +By default, we recommend the use of the SKOS lexicalization (`skos:definition`) in the core ontology layer. In the future this could be controlled by a flag in the configuration of the transformation tool. With such a flag one could enable RDFS lexicalization (`rdfs:comment`) instead of, or in addition to, the SKOS lexicalization. + + +[#rule:element-definition-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D.1}. Description -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a description for UML element. *TODO:* Update +==== + +[cols="a,a", options="noheader"] +|=== +| +.Description in Turtle syntax +[source,Turtle] +---- +:ResourceName + skos:definition "Description of the resource meaning"@en ; +. +---- +| +.Description in RDF/XML syntax +[source,XML] +---- + + Description of the resource meaning + +---- +|=== + +[#rule:element-definition-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D.1}. Description -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify a description for UML element. *TODO:* Update +==== + +[cols="a,a", options="noheader"] +|=== +| +.Note declaration for NodeShape in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix rdfs: . + +shape:ClassName + rdfs:comment "Description of the meaning of the class" ; +. +---- +| +.Note declaration for NodeShape in RDF/XML syntax +[source,XML] +---- + + Description of the meaning of the class + +---- + +| +.Note declaration for PropertyShape in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . + +shape:ClassName-PropertyName + sh:description "Description of the meaning of the property" ; +. +---- +| +.Note declaration for PropertyShape in RDF/XML syntax +[source,XML] +---- + + Description of the meaning of the property + +---- +|=== + + +=== Comment + +In accordance with , every kind of UML Element may own Comments (see <>). They add no semantics but may represent information useful to the reader. In OWL it is possible to define the annotation axiom for OWL Class, Datatype, ObjectProperty, DataProperty, AnnotationProperty and NamedIndividual. The textual explanation added to UML Class is identified as useful for conceptual modelling , therefore the Comments that are connected to UML Classes are taken into consideration in the transformation. + + +.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. + +By default, we recommend the use of the SKOS lexicalization (`skos:editorialNote`) in the core ontology layer. In the future this could be controlled by a flag in the configuration of the transformation tool. With such a flag one could enable RDFS lexicalization (`rdfs:comment`) instead of, or in addition to, the SKOS lexicalization. + +[#rule:element-external-comment-core,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D.1}. Comment -- in core ontology layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify annotation axiom for UML Comment associated to a UML element. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Comment in Turtle syntax +[source,Turtle] +---- +:ClassName + skos:editorialNote "This is an additional comment on ClassName"@en ; +. +---- +| +.Comment in RDF/XML syntax +[source,XML] +---- + + This is an additional comment on ClassName + +---- +|=== + +[#rule:element-external-comment-ds,source,XML,caption='',title='{example-caption} {counter:rule-cnt:D.1}. Comment -- in data shape layer',reftext='{example-caption} {rule-cnt}'] +==== +Specify an annotation on the data shape for the UML Comment associated to a UML element. +==== + +[cols="a,a", options="noheader"] +|=== +| +.Note declaration for NodeShape in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix rdfs: . + +shape:ClassName + rdfs:comment "This is an additional comment on ClassName" ; +. +---- +| +.Note declaration for NodeShape in RDF/XML syntax +[source,XML] +---- + + This is an additional comment on ClassName + +---- + +| +.Note declaration for PropertyShape in Turtle syntax +[source,Turtle] +---- +@prefix shape: . +@prefix sh: . +@prefix rdfs: . + +shape:ClassName-PropertyName + sh:description "This is an additional comment on PropertyName" ; +. +---- +| +.Note declaration for PropertyShape in RDF/XML syntax +[source,XML] +---- + + This is an additional comment on PropertyName + +---- +WARNING: *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)? \ No newline at end of file diff --git a/docs/modules/ROOT/pages/transformation/uml2owl-transformation.adoc b/docs/modules/ROOT/pages/transformation/uml2owl-transformation.adoc index ff40f5d..6717466 100644 --- a/docs/modules/ROOT/pages/transformation/uml2owl-transformation.adoc +++ b/docs/modules/ROOT/pages/transformation/uml2owl-transformation.adoc @@ -1,3 +1,80 @@ = Transformation of the UML model into derivative artefacts -*[TODO: add text and pages]* +[[sec:introduction]] +== Introduction + +Publications Office of the European Union set off to build an eProcurement ontology well motivated in . The ultimate objective of the project is to put forth a commonly agreed ontology that will conceptualise, formally encode and make available in an open, structured and machine-readable format data about public procurement, covering end-to-end procurement, i.e. from notification, through tendering to awarding, ordering, invoicing and payment . + +The process and the methodology adopted involve modelling the conceptual model in Unified Modelling Language (UML) and then, by abiding a set of conventions and recommendations, transform that model into a formal ontology expressed in Web Ontology Language (OWL) . + +This document provides a working definition of the transformation rules from the UML conceptual model into the formal ontology and validation data shapes. These rules are organised in accordance with the eProcurement ontology architecture . + +=== State of the art + +Much has been written about correspondences and between and transformation from UML to OWL and vice versa . The most significant literature on this topic was published between 2006 and 2019 comprising three book chapters, nine journal papers and multiple conference papers. + +The work presented in transforms into OWL some selected elements of UML models containing multiple UML class, object and state-chart diagrams in order to analyse consistency of the models. A similar approach is presented in , which is focused on detecting inconsistency in models containing UML class and state-chart diagrams. + +The papers investigate the differences and similarities between UML and OWL in order to present transformations of selected (and identified as useful) elements of UML class diagram. In , the need for UML–OWL transformation is additionally motivated by not repeating the modelling independently in both languages. + +The paper compares OWL abstract syntax elements to the equivalent UML features and appropriate OCL statements. The analysis is conducted in the direction from OWL to UML. For every OWL construct its UML interpretation is proposed. + +The works presented in are focused on extracting ontological knowledge from UML class diagrams and describe some UML–OWL mappings with the aim to reuse the existing UML models and stream the building of OWL domain ontologies. + +In is presented a comprehensive review of the related work. We use it as a guideline for ensuring the necessary coverage of the transformation rules specified in this report. It is important to note here that all the UML elements are treated here, but only the ones employed in the eProcurement conceptual model. + +=== How to read this document + +The reminder of this document comprises four sections covering major UML aspects. Section xref:transformation/transf-rules1.adoc#sec:tran-rules[Transformation of UML classes and attributes] treats classes and attributes. Following section deals with the main connector types employed in the eProcurement model, namely: associations, dependencies and generalisations. Section #sec:tran-rules3[[sec:tran-rules3]] explains how the datatypes and enumerations should be transformed and, finally, Section #sec:tran-rules4[[sec:tran-rules4]] provides a few transformation rules that are applicable to all UML elements and are concerned with comments, labels and notes. + +Each section provides a table with overview of the transformation rule set comprised within. The table provides three columns, one for every layer of the ontology architecture comprising rules: (a) , (b) , and (c) . + +Transformation rules are specified in a normative language and are aided by prototypical UML diagram fragments (usually preceding the rule) along with representation of the corresponding OWL fragment depicted in Graffoo visual notation . The diagrams are provided side to side in order to increase comprehension, with UML fragment on the left constituting the source of the transformation and the OWL fragment on the right representing the final result of the transformation. + +Each transformation rule is accompanied by the formal OWL representation, in Turtle and RDF/XML syntaxes, corresponding to the depicted UML fragment from the preceding figure. RDF/XML is a syntax to express RDF graphs as an XML document. Turtle is a textual syntax for RDF that is compact and resembles a natural text form with abbreviations for common usage patterns and datatypes. + +=== UML visual notation + +This section provides the main UML elements employed in this document. A detailed description can be consulted in the standard specifications and in the user guide . + + +.UML visual notation for classes and attributes +[#fig:uml-classes] +image::f1.png[1] + +.UML visual notation for datatypes and enumerations +[#fig:uml-datatypes] +image::f2.png[2] + +.UML visual notation for association, generalisation, and dependency +[#fig:uml-associations] +image::f3.png[3] + + +<> depicts simple, abstract and regular classes with and without attribute specifications. Note that no class methods are ever employed as this document as the transformations aim at data structures only. + +<<#fig:uml-datatypes>> depicts a primitive datatype and an enumeration. No complex datatypes are depicted as they are treated in the same manner as classes are. + +<> depicts association, generalisation and dependency connectors as the only ones necessary to model the eProcurement conceptual model. + +=== Graffoo visual notation + +This section provides the main Graffoo elements employed in this document. A detailed description can be consulted in the OWL standard specifications and in the Graffoo user guide . + + +.Graffoo visual notation for classes, instances and datatypes +[#fig:graffoo-classes] +image::f4.png[4] + +.Graffoo visual notation for object and data properties and generic links +[#fig:graffoo-predicates] +image::f5.png[5] + + +A yellow rectangle with solid black border is used to declare classes. Solid black and labelled arrows are used to declare class axioms. A green rhomboid with solid black border is used to declare datatypes. Solid black and labelled arrows are used to declare class axioms. + +A pink circle with solid black border is used to declare individuals. Solid black and labelled arrows are used to declare axioms and assertions among individuals. + +A green solid line is used to declare data properties, where the empty circle at the beginning identifies the property domain while the empty arrow at the end indicates the property range. A blue solid line is used to declare object properties, where the solid circle at the beginning identifies the property domain while the solid arrow at the end indicates the property range. + +The following sections present the transformation rules necessary for converting the UML eProcurement conceptual model into a formal OWL ontology. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/uml/conv-attributes.adoc b/docs/modules/ROOT/pages/uml/conv-attributes.adoc index 94bff0e..ff4057e 100644 --- a/docs/modules/ROOT/pages/uml/conv-attributes.adoc +++ b/docs/modules/ROOT/pages/uml/conv-attributes.adoc @@ -17,11 +17,11 @@ 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". +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 attributes names across multiple classes. Unless, by design, attributes with the same name are shared across multiple classes. +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. @@ -39,14 +39,14 @@ Attributes shall be assigned cardinality specifications contextualised to the cl *Description:* -The attribute multiplicity should be specified indicating the minimum and maximum cardinality. The default [1] multiplicity shall be interpreted as unspecified as expressed as [0..*] in the OWL model. +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-multiplicity]] +[[sec:attributes-datatypes]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Attribute datatypes @@ -60,11 +60,11 @@ uml:Attribute shall be defined with generally accepted primitive datatypes. *Description:* -Each uml:Attribute must have a name and 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. +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. +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. +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]] |=== diff --git a/docs/modules/ROOT/pages/uml/conv-classes.adoc b/docs/modules/ROOT/pages/uml/conv-classes.adoc index a743f95..bc6e098 100644 --- a/docs/modules/ROOT/pages/uml/conv-classes.adoc +++ b/docs/modules/ROOT/pages/uml/conv-classes.adoc @@ -94,7 +94,7 @@ Circular inheritance must be avoided. *Description:* -This means that if a class B specialises a class A then A may not specialise B or any of the subclasses of B. +This means that if a class `B` specialises a class `A`, then `A` may not specialise `B` or any of the subclasses of `B`. [[sec:uml-class]] === Technical conventions on uml:Class elements diff --git a/docs/modules/ROOT/pages/uml/conv-connectors.adoc b/docs/modules/ROOT/pages/uml/conv-connectors.adoc index 5806710..5a72f95 100644 --- a/docs/modules/ROOT/pages/uml/conv-connectors.adoc +++ b/docs/modules/ROOT/pages/uml/conv-connectors.adoc @@ -3,16 +3,76 @@ [[sec:relations]] === Conventional recommendations on Relations -When establishing relations between concepts it is conventional to use verbs of action, state, process or relation such as such as "includes", "replaces", "manages". It is required to use a verb or a verb phrase for relationship terms. It should be in _lowerCamelCase_ such that latexmath:[$$] triples may actually be read as natural language clauses, e.g. "EconomicOperator offers ProcuredItem" [xref:references.adoc#ref:d2.01-2017[d2.01-2017]]. + +[[sec:connetors-names-with-verb]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Connector names + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +Relations are to be expressed through uml:Connector elements. It is recommended to use a verb in the uml:Connector element names. +|=== + +*Description:* + +When establishing relations between concepts it is conventional to use verbs of action, state, process or relation, such as "includes", "replaces", "manages". It is required to use a verb or a verb phrase for relationship terms. It should be in _lowerCamelCase_ such that latexmath:[$$] triples may actually be read as natural language clauses, e.g. "EconomicOperator offers ProcuredItem" [xref:references.adoc#ref:d2.01-2017[d2.01-2017]]. The verb phrase must be in present tense, if needed inflected as third person singular. If an additional level of specificity is needed a qualifying nominal phrase may be appended. + +[[sec:connetors-bidirectional]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* Bi-directional relations + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +Relationships are usually bi-directional, and the name for both directions should be provided. +|=== + +*Description:* + Relationships are usually bi-directional and the inverse one should be provided where it makes sense. Adjust the verb phrases in the predicates as appropriate, usually, by employing the _active and passive voice_ in the term formulation brings the desired result. For example, "uses/isUsedBy" and "refersTo/isReferredToBy" or "offers/isOfferedBy" [xref:references.adoc#ref:d2.01-2017[d2.01-2017]]. + +[[sec:connetors-inverse]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* Inverse relation + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +Semantically inverse relationships should be represented as two distinct uml:Connector elements. +|=== + +*Description:* + The name of the inverse relation should not be semantically inverted verb, such as in case of "buys/sells" , "open/closes". The semantically inverted dichotomies must be modelled in separate connectors because they represent different relations. For example the dichotomy "buys/sells" should be modelled as two pairs: "buys/isBoughtBy" and "sells/isSoldBy". When the relation is of different nature, more like an attribute, then prefixing and suffixing techniques can be employed. For example, in the Organisation Ontology [xref:references.adoc#ref:org-ontology[org-ontology]], the concepts of an "Organisation" and a "Site" are defined along with two relationships that are the inverse of each other: "Organisation hasSite Site" and "Site siteOf Organisation" [xref:references.adoc#ref:d3.1-2015[d3.1-2015]]. + +[[sec:connetors-inverse-def]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* Definition of inverse relations + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +It is recommended that the definition of both the relation and its inverse relation is provided. +|=== + +*Description:* + It is recommended that each relationship includes a definition of its inverse. Models should define such inverse pairs for relationships although this does not extend to attributes. For example, Dublin Core [xref:references.adoc#ref:dublin-core-metadata[dublin-core-metadata]] includes a property of "dateAccepted", there is no inverse property that would link a given date, which is expressed as a simple value, to all the documents accepted for publication on that date. @@ -21,34 +81,220 @@ Models should define such inverse pairs for relationships although this does not [[sec:association]] === Technical conventions on uml:Association +[[sec:association-btw-classes]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Associations connect classes + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Association elements connect two uml:Classes. +|=== + +*Description:* + The uml:Association connectors represent relations between source and target classes. The association connector cannot be used between other kinds of UML elements. + +[[sec:association-target]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Association connector name + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Association connector elements shall have either a name or a target role specified . +|=== + +*Description:* + A generic UML connector may have a name applied to it, and it may have source/target roles specified in addition. This provides flexibility to how the domain knowledge may be expressed in UML, however this freedom increases the level of ambiguity as well. Therefore, we foresee two distinct ways to express properties: using the connector generic name, or using the connector source/target ends. First, if a connector name is specified then no source or target roles can be provided. The name must be valid as it is used to generate the OWL property URI. The minimum and maximum cardinality of the relation must be specified as target multiplicity. The second, and recommended approach is if the connector has no name then the target role must be specified. Or the converse, if a target role is specified then no connector name can be specified. Optionally a source role may be provided. In this case the relation direction must be changed from "Source->Target" to "Bidirectional". Or conversely, if the connector direction is "Bidirectional" then source and target roles must be provided. No other directions are permitted. + +[[sec:association-multiplicity]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Association multiplicity + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Association connector elements shall have their target multiplicity specified. If source role is specified, also their source multiplicity must be specified. +|=== + +*Description:* + The target and source multiplicity must be specified accordingly indicating the minimum and maximum cardinality. + +[[sec:association-definition]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Association definition + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Association connector shall have a definition. +|=== + +*Description:* + It is recommended that each association has a definition. The definition is then used for each role as they stand for the same meaning manifested in the inverse direction. Additional, specific definition, can be specified along the target and source roles. + [[sec:dependency]] === Technical conventions on uml:Dependency + +[[sec:dependency-btw-class-and-enum]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Dependency connects classes to enumerations + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Dependency connectors connect a uml:Class element to a uml:Enumeration element. +|=== + +*Description:* + The dependency connector may be used between uml:Class and uml:Enumeration boxes, oriented from the class towards the enumeration. It indicates the class has an owl:ObjectProperty whose range is a controlled vocabulary. The connector must have direction "Source->Target". No other directions are acceptable. -The connector must have a valid name and no source/target roles are acceptable. The multiplicity must be specified at the target of the connector. -In the transformation process, for the reasoning purposes, the range of the property must be expressed as a range restriction using owl:oneOf the values from the enumeration Concept scheme. This is also valuable for generating SHACL shapes. +[[sec:dependency-name]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Dependency connector name + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Dependency connector elements shall have a valid name. +|=== + +*Description:* + +The connector must have a valid name and no source/target roles are acceptable. + + +[[sec:dependency-multiplicity]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Dependency multiplicity + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Dependency connector elements shall have their target multiplicity specified. +|=== + +*Description:* + +The multiplicity must be specified at the target of the uml:Dependency connector. + +In the transformation process, for the reasoning purposes, the range of the property must be expressed as a range restriction using `owl:oneOf` the values from the enumeration Concept scheme. This is also valuable for generating SHACL shapes. + [[sec:genaralization]] === Technical conventions on uml:Generalization -The uml:Generalization connector signifies a class-subClass relation and is transformed into rdfs:subClassOf relation standing between source and target classes. The connector must have no name or source/target roles specified in the UML model. -In case a model class should inherit a class from an external model then proxies must be created for those classes. For example if "Buyer" specialises an "org:Organization" then a proxy for "org:Organization" must be created in the "org" package. +[[sec:generalization-btw-classes]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Generalization connects classes and sub-classes + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Generalization connectors connect a uml:Class element to its superclass uml:Class element. +|=== + +*Description:* + +The uml:Generalization connector signifies a class-subClass relation and is transformed into `rdfs:subClassOf` relation standing between source and target classes. + + +[[sec:generalization-name]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* uml:Generalization connector with no name + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +uml:Generalization connector elements shall have no name or a target role specified. +|=== + +*Description:* + +The uml:Generalization connectors must have no name or source/target roles specified in the UML model. + + +[[sec:proxy-classes]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* Proxy classes + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +For classes defined in external models proxy uml:Class elements should be defined. +|=== + +*Description:* + +In case a model class should inherit a class from an external model then proxies must be created for those classes. For example, if `Buyer` specialises an `org:Organization`, then a proxy for `org:Organization` must be created in the `org` package. + + +[[sec:disjoint-subclasses]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* Disjoint subclasses + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +Subclasses of the same class, represented by multiple uml:Generalization connectors pointing to the same superclass, are assumed disjoint by default. Exceptions may exist and can be encoded. +|=== + +*Description:* + +In this specification, the subclasses are assumed disjoint by default, unless otherwise specified in the transformations script, or explicitly marked on the generalisation relation with `\<>` stereotype. For the converse case the `\<>` stereotype shall be used. + + + +[[sec:equivalent-classes]] +|=== +|{set:cellbgcolor: #a8c6f7} + *Title:* Equivalent classes + +|{set:cellbgcolor: #f5f8fc} +*Identifier* - + +|*Statement:* +Equivalent classes can be represented by using stereotypes on the uml:Generalization connectors. +|=== -In this specification, the subclasses are assumed disjoint by default, unless otherwise specified in the transformations script, or explicitly marked on the generalisation relation with <> stereotype. For the converse case the <> stereotype shall be used. +*Description:* In case two classes are equivalent, then the latexmath:[$<>$] or latexmath:[$<>$] stereotype should be used as a marker. diff --git a/docs/modules/ROOT/pages/uml/conv-datatypes.adoc b/docs/modules/ROOT/pages/uml/conv-datatypes.adoc index 6a0e731..1ec8168 100644 --- a/docs/modules/ROOT/pages/uml/conv-datatypes.adoc +++ b/docs/modules/ROOT/pages/uml/conv-datatypes.adoc @@ -20,7 +20,7 @@ This convention draws the distinction between primitive (or atomic) types (consi [[sec:uml-datatype]] -=== Technical conventions on uml:Datatype elements +=== Technical conventions on uml:DataType elements [[sec:primitive-datatypes]] |=== @@ -36,14 +36,12 @@ For primitive data types the already existing (standardized or commonly used) da *Description:* -It is recommended to employ the primitive datatypes that are already defined in XSD [xref:references.adoc#ref:xsd1.1-spec[xsd1.1-spec]] and RDF [xref:references.adoc#ref:rdf11[rdf11]], which cover the standard, and most common types. Thus, definitions of custom data types shall be avoided unless the model absolutely needs them. Such cases are, however, rare. +It is recommended to employ the primitive datatypes that are already defined in XSD [xref:references.adoc#ref:xsd1.1-spec[xsd1.1-spec]] and RDF [xref:references.adoc#ref:rdf11[rdf11]], which cover the standard and most common types. Thus, definitions of custom data types shall be avoided unless the model really needs them. Such cases are, however, rare. -The data types defined in the UML model (and custom ones) shall be reduced to their XSD equivalent using the correspondences from the xref:#tab:uml2xsd[] table below. +The data types defined in the UML model (and custom ones) are resolved into their XSD equivalent using the correspondences from the xref:#tab:uml2xsd[] table below. Note that the family of string datatypes is mapped to _rdf:langString_. This means that the instance data should provide a language tag for the textual data indicating how it should be read. This enables multilingual data specification. Also, note that Date is mapped to `xsd:date` and DateTime is mapped to `xsd:dateTime`. However, the `xsd:date` is not included in the OWL2 interpretation and instead a strong preference is expressed for `xsd:dateTime`. Therefore, it is recommended to follow the OWL2 specification, although the `xsd:date` is a valid datatype in the RDF data and in SPARQL queries. Note that from the family of string datatypes we recommend using the following ones (in this order of preference): `rdf:PlainLiteral`, `rdfs:Literal`, `xsd:string`, and `rdf:langString`. Often enabling multilingual data specification is a necessity. -Also, note that Date is mapped to `xsd:date` and DateTime is mapped to `xsd:dateTime`. However, the `xsd:date` is not included in the OWL2 interpretation and instead a strong preference is expressed for `xsd:dateTime`. Therefore, it is recommended to follow the OWL2 specification, although the `xsd:date` is a valid datatype in the RDF data and in SPARQL queries. - [[tab:uml2xsd]] .UML to XSD datatype correspondences [cols="^,^",options="header",] @@ -77,7 +75,7 @@ The table above provides a simplified correspondence between UML and XSD datatyp *Identifier* - |*Statement:* -Even among the XSD and RDF datatypes, OWL 2 compliant datatypes shall be preferred. +Whenever possible, OWL 2 compliant XSD and RDF datatypes shall be used. |=== *Description:* @@ -93,12 +91,12 @@ We strongly recommended the use of OWL 2 compliant XSD and RDF standard datatype *Identifier* - |*Statement:* -For already existing datatypes, proxy uml:DataType elements should be defined. +For already existing datatypes proxy uml:DataType elements should be defined. |=== *Description:* -For the model consistency, it is recommended that the proxy data types be defined in the model for the XSDfootnote:[https://www.w3.org/2011/rdf-wg/wiki/XSD_Datatypes] and RDF data typesfootnote:[https://www.w3.org/TR/rdf11-concepts/#section-Datatypes] used in the model. The proxies must follow the standard namespace convention using the "rdf" and "xsd" prefixes. +For the model consistency, it is recommended that the proxy data types be defined in the model for the XSDfootnote:[https://www.w3.org/2011/rdf-wg/wiki/XSD_Datatypes] and RDF data typesfootnote:[https://www.w3.org/TR/rdf11-concepts/#section-Datatypes] used in the model. The proxies must follow the standard namespace convention using the `rdf:` and `xsd:` prefixes. [[sec:datatypes-references]] @@ -115,4 +113,4 @@ uml:DataType elements shall not connect to other elements. They can only be refe *Description:* -There should be no outgoing connectors from a uml:DataType element. They should be only referred to, most commonly, by being used as the data type of a uml:Attribute element. Declarations of uml:Datatype elements that are not referred to should be avoided, in order to keep the model lean and clean. \ No newline at end of file +There should be no outgoing connector from a uml:DataType element. uml:DataType elements should only be referred to, most commonly, by being used as the type of a uml:Attribute element. Declarations of uml:DataType elements that are not referred to should be avoided in order to keep the model lean and clean. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/uml/conv-general.adoc b/docs/modules/ROOT/pages/uml/conv-general.adoc index 76820f9..12b47a2 100644 --- a/docs/modules/ROOT/pages/uml/conv-general.adoc +++ b/docs/modules/ROOT/pages/uml/conv-general.adoc @@ -405,6 +405,7 @@ Encoded UTF-8 and UTF-16 names may be used [xref:references.adoc#ref:xml1-spec[x [[sec:stereotypes-tags]] === Stereotypes and Tags +[[sec:stereotypes]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Stereotypes @@ -422,6 +423,7 @@ The use of stereotypes is not recommended. There should be only a small set of s *See also:* SEMIC Style Guide Rule [https://semiceu.github.io/style-guide/public-review/gc-conceptual-model-conventions.html#sec:cmc-r17[CMC-R17]] +[[sec:tags]] |=== |{set:cellbgcolor: #a8c6f7} *Title:* Tags diff --git a/docs/supplemental-ui/favicon.ico b/docs/supplemental-ui/favicon.ico index b0702e6..fbe2f00 100644 Binary files a/docs/supplemental-ui/favicon.ico and b/docs/supplemental-ui/favicon.ico differ diff --git a/docs/supplemental-ui/img/alt_favicons/favicon16.ico b/docs/supplemental-ui/img/alt_favicons/favicon16.ico new file mode 100644 index 0000000..fbe2f00 Binary files /dev/null and b/docs/supplemental-ui/img/alt_favicons/favicon16.ico differ diff --git a/docs/supplemental-ui/img/alt_favicons/favicon16_2.ico b/docs/supplemental-ui/img/alt_favicons/favicon16_2.ico new file mode 100644 index 0000000..b508b8f Binary files /dev/null and b/docs/supplemental-ui/img/alt_favicons/favicon16_2.ico differ diff --git a/docs/supplemental-ui/img/alt_favicons/favicon48.ico b/docs/supplemental-ui/img/alt_favicons/favicon48.ico new file mode 100644 index 0000000..791e79f Binary files /dev/null and b/docs/supplemental-ui/img/alt_favicons/favicon48.ico differ diff --git a/docs/supplemental-ui/img/alt_favicons/favicon96.ico b/docs/supplemental-ui/img/alt_favicons/favicon96.ico new file mode 100644 index 0000000..58257b6 Binary files /dev/null and b/docs/supplemental-ui/img/alt_favicons/favicon96.ico differ diff --git a/docs/supplemental-ui/partials/head-icons.hbs b/docs/supplemental-ui/partials/head-icons.hbs new file mode 100644 index 0000000..c0cbb9e --- /dev/null +++ b/docs/supplemental-ui/partials/head-icons.hbs @@ -0,0 +1 @@ + \ No newline at end of file