How to Use model2owl

model2owl can be used in two ways:

Locally – Running the transformations on your own machine.
Online – Using the model2owl-boilerplate repository for automated execution.

Using model2owl Locally

Makefile

The Makefile automates various tasks such as running transformations, generating documentation, and executing tests. All commands are executed using the make build automation tool, which must be installed if not already available on your system.

Some make targets allow optional parameters. The project provides default values for parameters where applicable.

Example usage:

# Without parameters

make install

# With parameters

make owl-core XMI_INPUT_FILE_PATH=/home/mypc/work/model2owl/file1.xml OUTPUT_FOLDER_PATH=./my-folder

Setting Up Commands

The following commands are available for setting up dependencies:

get-saxon – Installs Saxon inside the project folder.
get-rdflib – Installs the RDFLib library.
get-widoco – Installs Widoco inside the project folder.
get-jinja – Installs Jinja2 inside the project folder.
get-jq – Installs jq inside the project folder.
install – Executes all the above installation steps automatically.
get-rdf-differ – Installs RDF Differ in a local directory.
start-rdf-differ-services – Starts Docker-based RDF Differ and Traefik services.
stop-rdf-differ-services – Stops RDF Differ Docker and Traefik services.
create-virtual-env – Creates a Python virtual environment for the project.

Functional Commands

These commands execute transformations and generate outputs:

generate-glossary – Generates an HTML glossary from the UML export (XML/XMI).
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_GLOSSARY_PATH – Path to the output folder.
generate-asciidoc-glossary – Generates an AsciiDoc glossary from the UML export (XML/XMI), optionally creating the model data JSON file if it is not provided.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the UML XMI model file required for generating the ReSpec data JSON file (used only if MODEL_DATA_JSON_PATH is not provided).
  - MODEL_DATA_JSON_PATH – (Optional) Path to the ReSpec data JSON file. If omitted, the file will be generated automatically.
  - OUTPUT_GLOSSARY_PATH – Output directory for the glossary file.
  - OUTPUT_FOLDER_PATH – (Optional) Directory where the generated ReSpec data JSON file should be stored (used only if MODEL_DATA_JSON_PATH is not provided). If not set, then the default directory is used.
generate-convention-report – Generates a compliance report from the UML export in HTML format.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_CONVENTION_REPORT_PATH – Path to the output folder.
generate-convention-SVRL-report – Generates a compliance report from the UML export in SVRL format.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_CONVENTION_REPORT_PATH – Path to the output folder.
owl-core – Generates a lightweight ontology from the UML export.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_FOLDER_PATH – Path to the output folder.
  - NAMESPACES_USER_XML_FILE_PATH – Path to the *.xml file containing namespaces.
  - IMPORTS_XML_FILE_PATH – Path to the *.xml file containing ontology URIs to be imported.
owl-restrictions – Generates a heavyweight ontology with additional axioms for reasoning.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_FOLDER_PATH – Path to the output folder.
  - NAMESPACES_USER_XML_FILE_PATH – Path to the *.xml file containing namespaces.
  - IMPORTS_XML_FILE_PATH – Path to the *.xml file containing ontology URIs to be imported.
shacl – Generates SHACL data shapes suitable for validation.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_FOLDER_PATH – Path to the output folder.
  - NAMESPACES_USER_XML_FILE_PATH – Path to the *.xml file containing namespaces.
  - IMPORTS_XML_FILE_PATH – Path to the *.xml file containing ontology URIs to be imported.
generate-jsonld-context – Generates JSON-LD context file for the ontology data.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_FOLDER_PATH – Path to the output folder.
  - JSONLD_CONTEXT_INDENTATION – Indentation for the JSON-LD context file (defaults to 2 spaces).
generate-html-docs-from-rdf – Generates HTML documentation using Widoco from an RDF file.
- Parameters:
  - WIDOCO_RDF_INPUT_FILE_PATH – Path to the RDF file.
  - OUTPUT_FOLDER_PATH – Path to the output folder.

generate-respec – Creates an HTML documentation package for an ontology using Jinja2 and ReSpec. The command expects the input model, metadata and a set of assets to be provided. The generated package is ready to be hosted on a web server. This command does not generate other RDF artefacts, so they need to be generated separately and provided as input to this command.
- Parameters:
  - RESPEC_OUTPUT_DIR – Output directory for the documentation package.
  - RESPEC_DATA_JSON_PATH – (Optional) Path to the ReSpec data JSON file. If not provided, the file will be generated automatically.
  - RESPEC_METADATA_JSON_PATH – Path to the metadata JSON file.
  - RESPEC_INPUT_ASSETS_DIR – Directory containing static assets (examples, images, etc.).
  - XMI_INPUT_FILE_PATH – (Optional) Path to the UML XMI model file needed for generating the ReSpec data JSON file (if not given).
  - OUTPUT_FOLDER_PATH – (Optional) Directory where a ReSpec data JSON file should be stored (if not given).
  - MODEL_EAP_FILE_PATH – Path to the UML EAP model file.
respec-json – An auxiliary command that generates the ReSpec data JSON file from the input XMI file. The command is used by the generate-respec command.
- Parameters:
  - XMI_INPUT_FILE_PATH – Path to the XMI file.
  - OUTPUT_FOLDER_PATH – Path to the output folder.
  - NAMESPACES_USER_XML_FILE_PATH – Path to the *.xml file containing namespaces.
  - IMPORTS_XML_FILE_PATH – Path to the *.xml file containing ontology URIs to be imported.
  - RESPEC_JSON_INDENTATION – (Optional) Number of spaces for indentation in the generated JSON file. Default is 2.
merge-owl-shacl – Merges an OWL ontology file with a SHACL shapes file into a combined output TTL file. Useful to extend the final report with selected properties related to constraint information, which is not typically available or available only inconsistently from lightweight ontologies. At least the new version being compared must be merged, if not both.
- Parameters:
  - MERGE_ONTOLOGY_FILE – Path to the OWL ontology file (default: test/diffing-files/ePO_core-4.1.0.ttl).
  - MERGE_SHAPES_FILE – Path to the SHACL shapes file (default: test/diffing-files/ePO_core_shapes-4.1.0.ttl).
  - MERGE_OUTPUT_FILE – Path to the output file (default: ${OUTPUT_FOLDER_PATH}/ePO_core_combined-1.0.ttl).
run-rdf-diff – Runs the RDF diffing workflow using RDF Differ services and produces a diff report. The report type is determined by the RDF_DIFF_TEMPLATE.
- Parameters:
  - RDF_DIFF_FILE1 – Path to the first (old version) RDF file (default: test/diffing-files/ePO_core-4.1.0.ttl).
  - RDF_DIFF_FILE2 – Path to the second (new version) RDF file (default: test/diffing-files/ePO_core-4.2.0.ttl).
  - RDF_DIFF_OUTDIR – Output directory for the diff results (default: ${OUTPUT_FOLDER_PATH}).
  - RDF_DIFF_AP – Application profile used for diffing (default: owl-core-en-only).
  - RDF_DIFF_TEMPLATE – Template format for the diff report (default: html).
merge-xmi – Merges XMI files from a specified folder.
- Parameters:
  - FIRST_XMI_TO_BE_MERGED_FILE_PATH – Path to the first XMI file.
  - XMI_MERGED_OUTPUT_FOLDER_PATH – Path to the output folder.
convert-to-turtle – Converts RDF files to Turtle format.
- Parameters:
  - ONTOLOGY_FOLDER_PATH – Path to the folder containing RDF files.
convert-to-rdf – Converts Turtle files to RDF format.
- Parameters:
  - ONTOLOGY_FOLDER_PATH – Path to the folder containing Turtle files.

Installation

Prerequisites

Ensure the following are installed on your system:

make
Python 3

Installation Steps

1.Clone model2owl repository:

git clone https://github.com/example/model2owl.git

2.Run the installation command:

make install

Note: If you do not have a virtual environment set up, create one using:

make create-virtual-env

# Then activate it:

source model2owl-venv/bin/activate

Configuration

The model2owl configuration consists of six files, which should be placed in a single folder:

config-parameters.xsl – Defines main configuration variables.
namespaces.xml – Lists namespaces used in the UML model.
imports.xml – Contains URIs of ontologies to be imported.
umlToXsdDataTypes.xml – Maps UML data types to XSD.
xsdAndRdfDataTypes.xml – Defines data types used.
metadata.json – Contains metadata describing the processed model, which is used to generate RDF and ReSpec artefacts.

In addition, configuration for a workflow implementing the RDF diffing feature can be set using a dedicated diff-config.env file (among other options described on the RDF Diffing documentation page).

To set up, copy the default configuration files from the ePO-default-config folder to your new configuration folder.

All configuration files should be stored in one folder. Once the configuration is set, update config-proxy.xsl to point to the new configuration folder. The config-proxy.xsl file serves as a central link to the main configuration file for model2owl. It allows the tool to reference and apply the configuration stored at a specified location. By modifying this file, users can switch between different configuration sets.

Example:

# Update the path in config-proxy.xsl:
<xsl:import href="my-pc/user/my-config-folder/config-parameters.xsl"/>

Configuration Parameters

To adjust configuration settings, edit the config-parameters.xsl file.

Important notes:

Do not modify the namespacePrefixes, umlDataTypesMapping, xsdAndRdfDataTypes, or metadataJson variables.
Ensure any modified variable retains its original datatype (boolean, string, list).

Listing 1. Example of correct and incorrect datatype modification:

# Correct
<xsl:variable name="defaultNamespaceInterpretation" select="fn:true()"/>

# Incorrect (datatype mismatch)
<xsl:variable name="defaultNamespaceInterpretation" select="'new-value'"/>

For more details about available variables and how they work, please visit the configuration parameters page

Namespaces Configuration

To add namespaces, edit namespaces.xml. The purpose of the file is to store definitions of namespaces, including their prefixes and URIs.

Add a prefix and its corresponding URI in the namespaces.xml file in the following way:

<prefix name="foaf" value="http://xmlns.com/foaf/0.1/"/>

Imported ontologies configuration

URIs of ontologies to be declared for import within generated ontologies (for core, restrictions or SHACL shapes artefacts) can be specified in the imports.xml file. The file includes sections for shared URIs, which apply to all artefact types, as well as sections for specific artefact types. URIs specified in the imports.xml file will be included in the generated artefacts as import statements using the owl:imports property.

Listing 2. Example of imported ontologies configuration:

<imports xmlns="http://publications.europa.eu/ns/">
    <!-- affects all three artefacts -->
    <all>
        <import uri="http://purl.org/dc/terms/"/>
    </all>
    <!-- affects SHACL artefact -->
    <shacl>
        <import uri="http://data.europa.eu/a4g/data-shape#awa-shape"/>
    </shacl>
</imports>

The exemplary configuration will cause all RDF output files to include the following import statement for the declared ontology:

<!-- in core.rdf, the resource <http://example.com/core> is of type owl:Ontology -->
<rdf:Description rdf:about="http://example.com/core">
    <owl:imports rdf:resource="http://purl.org/dc/terms/"/>
</rdf:Description>

<!-- in core_restrictions.rdf, the resource <http://example.com/core-restriction> is of type owl:Ontology -->
<rdf:Description rdf:about="http://example.com/core-restriction">
    <owl:imports rdf:resource="http://purl.org/dc/terms/"/>
</rdf:Description>

<!-- in core_shapes.rdf, the resource <http://example.com/core-shape> is of type owl:Ontology -->
<rdf:Description rdf:about="http://example.com/core-shape">
    <owl:imports rdf:resource="http://purl.org/dc/terms/"/>
</rdf:Description>

In addition, the below statement will be present only in the SHACL artefact:

<!-- in core_shapes.rdf, the resource <http://example.com/core-shape> is of type owl:Ontology -->
<rdf:Description rdf:about="http://data.europa.eu/a4g/ontology#core-restriction">
    <owl:imports rdf:resource="http://data.europa.eu/a4g/data-shape#awa-shape"/>
</rdf:Description>

To add additional URIs, simply include more <import uri="…"/> elements within the appropriate section of the imports.xml file (either all, or the one corresponding to the artefact of interest, e.g., shacl).

XSD and RDF Data Types

To define datatypes used in the UML model, edit xsdAndRdfDataTypes.xml:

<datatype namespace="xsd" qname="xsd:date"/>

UML to XSD Mappings

If the UML model uses custom datatypes, map them in umlToXsdDataTypes.xml:

<mapping>
    <from qname="epo:Date"/>
    <to qname="xsd:date"/>
</mapping>

Metadata JSON

All predefined properties should be updated in the metadata.json file by the editor as described in Metadata parameters. The editor can also add custom properties to be used in the generated ReSpec documentation as described in Custom metadata section.

Diff workflow file

The diff workflow uses a dedicated diff-config.env configuration file located in the workflow directory. The file follows a simple bash env file syntax.

The below is an example of such a file:

# Version to compare against (branch/tag/commit)
REVISION_TO_COMPARE_COMMIT_ID=main

# External repository URL (leave empty for same repo)
REVISION_TO_COMPARE_REPO_URL=

# Root directories for OWL/SHACL files
OLD_ONTOLOGY_DIR=implementation
NEW_ONTOLOGY_DIR=implementation

# Modules to diff (comma-separated, empty = auto-detect)
MODULES=

# Output directory for diff reports
RDF_DIFF_OUTDIR=diff-reports

The expected configuration properties are described in the RDF diffing configuration section.

Running Transformations

Once installed and configured, you can run different transformations using make commands. Each command generates specific artefacts that correspond to different key capabilities of model2owl.

Commands and Generated Files

make owl-core – Generates a lightweight ontology from the UML model.
- Generated File: <input-file>.rdf – Lightweight OWL Core ontology in RDF format.
make owl-restrictions – Generates heavyweight ontology with additional axioms suitable for reasoning purposes.
- Generated File: <input-file>_restrictions.rdf – OWL Restrictions ontology.
make shacl – Generates SHACL shapes for data validation.
- Generated File: <input-file>_shapes.rdf – SHACL shapes in RDF format.
make generate-jsonld-context – Generates JSON-LD context for JSON-LD applications.
- Generated File: <input-file>_context.jsonld – Signatures of ontology terms usable in a JSON-LD data file. The file consists of a JSON object with a single top-level entry having the @context key and an object with term definitions as its value.
make generate-glossary – Generates an HTML glossary of terms extracted from the UML model.
- Generated File: <input-file>_glossary.html – Glossary in HTML format.
make generate-asciidoc-glossary – Generates an AsciiDoc glossary of terms extracted from the UML model.
- Generated File: <input-file>_glossary.adoc – Glossary in AsciiDoc format.
make generate-convention-report – Generates a compliance report from the UML model in HTML format, validating it against the conventions.
- Generated File: <input-file>_convention_report.html – HTML compliance report.
make generate-convention-SVRL-report – Generates a compliance report in SVRL format.
- Generated File: <input-file>_convention_svrl_report.xml – SVRL compliance report.
make generate-respec – Generates a ReSpec documentation package.
- Generated folder: <respec-dir> – A folder containing the HTML ReSpec document and all required resources (artefact files, images, examples, and other static assets). The package structure is described in ReSpec package structure.
make merge-owl-shacl – Merge OWL ontology and SHACL shapes files. Used as a preprocessing step before calling run-rdf-diff.
- Generated File: <output-dir>/<file-name>.ttl – An RDF file combining content of provided OWL core and SHACL shapes artefacts, resulting in an OWL-SHACL RDF file (embedded SHACL shapes).
make run-rdf-diff – Generates a diff report in a format specified by the user (JSON / AsciiDoc / HTML).
- Generated File: <output-dir>/diff.<report-extension> – A diff report listing changes between two versions of an RDF file.

Notes

<input-file> will be replaced with the name of the input XMI file (e.g., file1.rdf if the input is file1.xml).
These commands provide flexibility in generating individual artefacts or multiple artefacts based on your needs.

Example of transformation command:

make owl-core XMI_INPUT_FILE_PATH=/home/mypc/work/model2owl/file1.xml OUTPUT_FOLDER_PATH=./my-folder

Using model2owl online

Model2owl-boilerplate (and its forked versions) can be used to run model2owl in an automated workflow hosted on GitHub Actions. The project repository provides a ready-to-use setup for executing model2owl transformations and generating artefacts based on a UML model stored in the same repository. The transformation can be configured in the same way as the local setup by modifying model2owl configuration files. Additionally, the diff workflow can be configured through a dedicated config file (among other options described on the RDF Diffing documentation page). Both the model2owl configuration files and the diff workflow config file are described in the Configuration section. Both the transformation and diffing workflows support processing multiple ontology modules in a single run. In order to process one or more modules, the user needs to provide dedicated directories for each module containing the UML model and configuration files.

The workflows expect a specific structure and naming conventions for the input files and directories that are realized in the model2owl-boilerplate repository and need to be followed in other repositories based on it. The conventions are described in the Usage section.

More details about using model2owl-boilerplate can be found in the repository’s README file.