weso / hermes Goto Github PK

A ShExCSV to ShExC Translator.

License: MIT License

Java 98.83% Makefile 1.17%

hermes's Introduction

Hermes: A ShExCSV to ShExC Translator

Hermes is developed and maintained by WESO Research Group. Hermes is a Java based library that allows to translate from Shape Expressions tabular formats like ShExCSV to the Shape Expressions Compact Syntax.

This library can be enveloped in to a rest api server and used form other languages but at the moment that feature is not provided within this repository. In order to see the roadmap of the project you can refeer to Long Term Roadmap (LTR) issue.

How to use

Once you have your environment ready you can start using Hermes from your CLI as follows:

hermes --prefixesFile=prefixes.csv --shapesFile=shapes.csv --outDir=./out

Prefixes File

The prefixes file is a CSV file that contains all the prefix declarations that will be used by the Shape Expressions that are in the shapes.csv file. The format of this file is as follows:

Prefix	URI
	http://example.org/
xsd	http://www.w3.org/2001/XMLSchema#
foaf	http://xmlns.com/foaf/0.1/
...	...

Shapes File

The shapes file is a CSV file tht contains all the shapes declarations. It uses the prefixes defined at prefixes.csv file. The format of this file is as follows:

Shape Label	Constraint Property	Constraint	Min	Max
:User	schema:name	xsd:string	1	1
:User	schema:bithday	xsd:date	0	1
:User	schema:gender	[ schema:Male schema:Female ] OR xsd:string	1	1
:User	schema:owns	@:Car	0	-
:Car	schema:plateNumber	xsd:string	1	1
...	...	...	...	...

Generated File

For the previous input files Hermes will generate in te uotput directory a Shape Expression Compact Syntax file as follows:

PREFIX :       <http://example.org/>
PREFIX schema: <http://schema.org/>
PREFIX xsd:    <http://www.w3.org/2001/XMLSchema#>

:User {
  schema:name          xsd:string {1,1} ;
  schema:birthDate     xsd:date {0,1} ;
  schema:gender        [ schema:Male schema:Female ] OR xsd:string {1,1} ;
  schema:owns         @:Car {0,}
}

:Car {
  schema:plateNumber   xsd:string {1,1} ;
}

License

Hermes is primarily distributed under the terms of the MIT license.

See LICENSE for details.

hermes's People

Contributors

Watchers

Forkers

thewillyhuman

hermes's Issues

🚀 Long Term Roadmap (LTR)

🚧 This is our roadmap 🚧

This issue tracks high-level plans for hermes. It gives entry points for release-level issues as well as broader goals that correspond to rough milestones over the next year. In practice, these goals are pretty hit-and-miss w.r.t. people actually doing the necessary work, but they are reported here as aspirations and for discussion.

Release plans

hermes 1.0 beta - expected October 2020
hermes 1.0 release candidate - expected November 2020
hermes 1.0 stable release - expected December 2020
hermes 2.0 beta - expected March 2021
hermes 2.0 release candidate - expected April 2021
hermes 2.0 stable release - expected May 2021
- hermes 2.5 LTS - expected June 2020

Primary focus of each version

hermes 1.0: Translation from ShExCSV to ShExC.
hermes 2.0: Binding with other programming languages and API Rest.
- hermes 2.5 LTS: First production ready release with long term support 🎉.

Automatically publish to GitHub Packages when pushed to master

Expected
Every time a push is done to master (a new stable version), publish a package in GitHub Packages.

Hermes translator target

Introduction

The high-level architecture of the CVS to ShEx translation system is presented. For this, two approaches are proposed.

Proposal 1

It is proposed that the generation of shapes be done as follows. All prefixes and shapes are compacted into a single compact ShEx syntax file.

Proposal 2

It is proposed that the generation of shapes be done as follows. For each input csv file that contains a ShEx, generate an output file containing only that shape expression together with the prefixes. This would mean that there would be as many output files as shapes in input CSV.

Developer should be able to test and build the sources from make tool

As a Developer
I want to be able to test and build the sources from the make tool
Because I don't want to know any specific details about grade/maven etc...

ADR: Separate prefixes and shapes in different files

Separate prefixes and shapes in different files

This ADR focuses on choosing an option regarding whether prefixes and shapes are combined in a single file or if they are separated into different files.

Context

An architectural decission that has to be made is if the prefixes are within the same CSV file as the shape expressions. The main gal of separating them is to apply the single resposability principle. That is, each file contains only one piece of the context and therefore we acchieve cleaner files. But with that said if we separate the prefixes from the shapes file then we will not be able to use some features like prefix override.

User and developer should be able to use the tool over a REST API

As a User and as a Developer
I want to be able to use the tool by means of a REST API
Because I dont want to deploy the artifact on all the systems where I will use the tool

Developer should be able to import the tool in other java based projects

As a developer
I want to be able to import the tool in other java based projects
Because I need it to automate the comunication between my project and this tool

Use cases definition

This thread is offered to create and discuss the most expected use cases of the hermes translation system.

The objective of this project is to allow translation from a tabular format like CSV to ShEx Compact Syntax. For this, the input format is structured as follows.

CSV file with the list of prefixes that the shapes will use.
List of CSV files with shape expressions. Each CSV represents the triple constraints of a single shape.