convert: RDF Data model conversions

rudof supports conversion between different RDF Data modeling technologies using the convert command. At this moment, we have implemented some converters listed in the table below.

The convert command requires 7 main arguments; namely:

• --input-mode (-m for short), where the user introduces the input technology.
• --export-mode (-x for short), where the user introduces the output technology.
• --format (-f for short), where the user defines the input file format (serialization-wise).
• --result-format (-r for short), where the user defines the output file format (serialization-wise).
• --source-file (-s for short), where the user passes the input file path.
• --output-file (-o for short), where the user passes the output file path.
• --config-file (-c for short), where the user passes the config file path.

Note that there’s a difference between mode and format. While the first allows users to select the RDF technology; namely, DCTAP, SHACL or ShEx, the second allows users to define the actual serialization format employed; e.g. ShEx can be serialized using compact syntax (ShExC) or JSON (ShExJ).

Prerequisites

Generating svg or png visualizations — UML diagrams from convert/shex, or RDF graphs from data — needs an external drawing tool. rudof supports two, selectable with --viz-engine:

PlantUML (default)

Download the command line JAR file and set the PLANTUML environment variable to point to it:

export PLANTUML=/path/to/plantuml.jar

PlantUML also requires Java 8 or higher to be installed. You can check if you Java is already installed by running the following command.

java --version

Graphviz

Install Graphviz through your system’s package manager so that the dot command ends up on PATH — unlike PlantUML, no environment variable is needed:

# Debian/Ubuntu
sudo apt-get install graphviz
# macOS (Homebrew)
brew install graphviz

You can check it’s installed with:

dot -V

Choosing a visualization engine

Pass --viz-engine graphviz to use Graphviz instead of the PlantUML default, on any command that supports svg/png output — data, shex, and convert:

rudof convert -s simple.shex -m shex -x uml -r svg --viz-engine graphviz -o simple.svg

Both engines are driven by the same style settings, so svg/png output looks the same regardless of which one generated it — see [shex2uml].class_skin in the config reference to customize UML class-diagram colors.

For sucessfully following the examples provided, download the files from the Github repository.

curl -o book.csv https://raw.githubusercontent.com/rudof-project/rudof/refs/heads/master/examples/dctap/book.csv
curl -o simple_shacl.ttl https://raw.githubusercontent.com/rudof-project/rudof/refs/heads/master/examples/simple_shacl.ttl
curl -o simple.shex https://raw.githubusercontent.com/rudof-project/rudof/refs/heads/master/examples/simple.shex

Configuration files

Configuration files can be used to pass additional parameters to the conversion process. In the Github repository, an example configuration file is provided. Note that those are TOML files.

curl -o config.toml https://raw.githubusercontent.com/rudof-project/rudof/refs/heads/master/examples/dctap/book_converter_config.toml

Whose contents are described below.

[tap2shex]
base_iri = "http://example.org/"

[tap2shex.prefixmap]
dct = "http://purl.org/dc/terms/"
rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
foaf = "http://xmlns.com/foaf/0.1/"
xsd = "http://www.w3.org/2001/XMLSchema#"
sdo = "https://schema.org/"
ex = "http://example.org/"

From DCTAP

DCTAP is an RDF data model technology developed at the Dublin Core Application Profiles Working Group which aims for providing a way to represent application profiles in the form of tables.

From DCTAP to ShEx

It is possible to convert from a DCTap (CSV) to ShEx. In the first example, the most simple DCTap to ShEx schema conversion is described.

rudof convert -m dctap -s book.csv -f csv -x shex -r shexc

However, the converter contains a parameter that can be used to add configuration information (--config-file). For example, instead of the basic prefix map, we can use custom prefix map declarations as follows. Refer to the Configuration files section.

rudof convert -s book.csv -m dctap -x shex -f csv -c config.toml -r shexc

From DCTAP to UML

Conversion for DCTap (CSV) to UML-like visualizations is possible. In fact, it is possible to serialize the resulting diagram in two possible formats, namely, svg and png. For indicating rudof the desired format use the --result-format (-r for short) argument.

To generate svg visualizations it can be done as follows:

rudof convert -s book.csv -m dctap -x uml -f csv -r svg -o simple.svg

To generate png visualizations it can be done as follows:

rudof convert -s book.csv -m dctap -x uml -f csv -r png -o simple.png

Add --viz-engine graphviz to render with Graphviz instead of the PlantUML default — see Choosing a visualization engine.

From DCTAP to HTML

TBD

From SHACL

From SHACL to ShEx

It is possible to convert between a subset of SHACL shapes to ShEx schemas. As an example, the following command:

rudof convert -m shacl -x shex -s simple_shacl.ttl -f turtle -o simple.shex

The converter only works for a subset of SHACL. This is a work-in-progress feature and the following issue is expected to document the subset of SHACL supported.

Specifying base IRI to handle relative IRIs

If the RDF data contains relative IRIs, it is necessary to resolve them by specifying a base IRI. It can be done by providing a base declaration in the [rdf] entry of the configuration file. For example, assuming the configuration file contains examples/config/data_config.toml

[rdf]
base_iri = "http://example.org/"

it is possible to specify the conversion as:

rudof convert -m shacl -x shex -s simple_shacl.ttl -f turtle -o simple.shex -c examples/config/data_config.toml

From ShEx

From ShEx to UML

As in the case of DCTap, it is possible to convert from a simple ShEx schema to UML like visualization in svg and png. To generate svg visualizations it can be done as follows:

rudof convert -s simple.shex -m shex -x uml -r svg -o simple.svg

To generate png visualizations it can be done as follows:

rudof convert -s simple.shex -m shex -x uml -r png -o simple.png

Add --viz-engine graphviz to render with Graphviz instead of the PlantUML default — see Choosing a visualization engine. rudof shex -r svg/-r png (see shex: ShEx visualization) is a more direct route to the same diagram when the schema is already loaded and you don’t need convert’s DCTAP/SHACL input support.

From ShEx to HTML

It is possible to convert from ShEx schema to a set of HTML pages representing the schema. The content of the HTML pages can be customized using Jinja templates. The generated pages will be stored in an output folder that must be specified with the --target-folder option.

rudof convert -s simple.shex -m shex -x html -t output-folder -e templates-folder

The HTML pages that are generated can be highly configured as rudof’s approach is based on templates. Thus, it takes a set of default templates which define the appearance of the resulting HTML. However, it is possible to use customized templates based on the minininja template engine.