Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cefriel/mapping-template

A template-based component exploiting Apache Velocity to define declarative mappings for schema and data transformations.
https://github.com/cefriel/mapping-template

rdf semantic-web template velocity-template

Last synced: 5 months ago
JSON representation

A template-based component exploiting Apache Velocity to define declarative mappings for schema and data transformations.

Awesome Lists containing this project

README 

          
# mapping-template



[![Maven Central](https://img.shields.io/maven-central/v/com.cefriel/mapping-template.svg?label=Maven%20Central)](https://search.maven.org/artifact/com.cefriel/mapping-template)



A template-based component exploiting [Apache Velocity](https://velocity.apache.org/) to define declarative mappings for schema and data transformations.



A quantitative and qualitative evaluation of the tool is available in the repository [mapping-template-eval](https://github.com/cefriel/mapping-template-eval).



### Mapping Template Language (MTL)



The [Wiki](https://github.com/cefriel/mapping-template/wiki/Mapping-Template-Language-(MTL)) contains the documentation to specify compliant mapping templates.



Example templates are provided in the [examples](https://github.com/cefriel/mapping-template/tree/main/examples) folder.



### RDF Mapping Language support (RML to MTL)



The `mapping template` supports the execution of RML mappings that are automatically compiled to an MTL template and executed. The `mapping template` is currently compliant with the `rml-core` specification (https://w3id.org/rml/portal).



The RML mapping can be passed with the `--rml` option for usage via CLI and a [test case](src/test/java/com/cefriel/template/RMLTests.java) is made available to exemplify the usage as a library.



### Usage as a Library



The  `mapping-template` can be used as a library through the `TemplateExecutor` class. It allows to execute mapping templates accessing data from the filesystem or through `InputStream`s. Configuration examples can be found in the `Main` class and in the `test` folder.



The `mapping-template` is available on Maven Central and can be added as a dependency in Java projects as described [here](https://search.maven.org/artifact/com.cefriel/mapping-template). Using Maven the following dependency should be specified in the `pom.xml` selecting a [release](https://github.com/cefriel/mapping-template/releases) version:

```



  com.cefriel

  mapping-template

  ${version}



```

The component can be used as an external library to launch multiple template executions in parallel.



### Usage via CLI

This is the intended usage of the `mapping-template.jar`.



```

usage: java -jar mapping-template.jar 

options:

  -b, --basepath             Base path for files (input, template, output). Default value is './'.

  -c, --contextIRI           IRI identifies the named graph for context-aware querying of the repository. 

                                  Default behaviour: the entire repository is considered for querying.

  -q, --query                Path to the file containing a query for parametric template execution.

  -dq, --debug-query              Saves in the output file the result of the query provided with -q option.

  -f, --format               Activate procedures for specific output formats. Supported values: 'xml' 

                                  (XML escape, XML parsing to check structure, indentation), 'turtle', 'rdfxml', 'nt', 'json'.

  -fir, --fail-invalid-ref        If this option is enabled, the execution fails every time a variable in the template can not be accessed.

  -fun, --functions          Provide the path to a Java file defining a TemplateFunctions subclass.

  -if, --input-format        Format for the input(s). Supported values are: 'csv', 'json', 'xml', 'rdf', 'mysql', 'postgresql'.

  -i, --input                Path for the input file. Multiple input files are supported if the '--input-format' is 'rdf'.

  -kv, --key-value           Path for a file containing a key:value pair for each line. These pairs

                                  are made available as a map in the template.

  -kvc, --key-value-csv      Path for a csv file with one line interpreted as a set of key[column]-value[line] pairs. 

                                  These pairs are made available as a map in the template.

  -o, --output               Path of output file. Default: output.txt

  -rml, --compile-rml        Provide an RML mapping file to be executed

  -t, --template             Path of template file. Default: template.vm

  -tm, --time                Path of file reporting template execution time. Default: timing not saved. 

  -tr, --trim                     Trim newlines from the template before executing it to reduce memory usage.

  -url, --remote-url         Address for accessing remote database (relational or triplestore).

  -id, --remote-id           Identifier of the remote database or repository for triplestores.

  -us, --username            Username for accessing remote database.

  -psw, --password           Password for accessing remote database.

  -v, --verbose                   Debug information are logged.

```

Instructions on how to run the example mapping templates via command line are provided in the [examples/README](https://github.com/cefriel/mapping-template/tree/main/examples/README.md).



A `$reader` is initialized based on the specified `-if` option. Additional `Reader`s should be defined in the template using the available functions.



If `-url` and `-id` options are set a remote database/repository is used for queries and the `-i`  option is ignored. If they are not set the `-i` option is mandatory. Assumptions to use a remote database/repository are: (i) it is up and running, and (ii) data are already in there.



### Usage via Chimera 



If you would like to use the `mapping-template` for more advanced integration scenarios, check out the integration within the [Chimera](https://github.com/cefriel/chimera) framework. Chimera is implemented on top of Apache Camel and offers components to define schema and data transformation pipelines based on Semantic Web solutions.



### Cite as



If you use the `mapping-template` for publications, cite the following article: 



> Scrocca, M., Carenini, A., Grassi, M., Comerio, M., & Celino, I. (2024). `Not Everybody Speaks RDF: Knowledge Conversion between Different Data Representations`. In: Fifth International Workshop on Knowledge Graph Construction co-located with the ESWC2024. CEUR-WS. https://ceur-ws.org/Vol-3718/paper3.pdf



Check the [Chimera](https://github.com/cefriel/chimera) repository for a list of projects using the `mapping-template`.



### Commercial Support



If you need commercial support for the `mapping-template` contact us at [chimera-dev@cefriel.com](mailto:chimera-dev@cefriel.com).



### Contributing



Before contributing, please read carefully, complete and sign our [Contributor Licence Agreement](https://github.com/cefriel/contributing/blob/main/contributor-license-agreement.pdf). 



When contributing to this repository, please first discuss the change you wish to make via issue or any other available method with the repository's owners.



### License



_Copyright (c) 2019-2025 Cefriel._



Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at



    http://www.apache.org/licenses/LICENSE-2.0



Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.