​Toolchain for Publishing Data Specifications - User Manual by SEMIC

Background

In the years of developing the Core Vocabularies, SEMIC has matured a lot of experience in managing the lifecycle of data specifications and their publications. After facing recurring update cycles, managing the propagation of the updates through the specifications dependencies, and orchestrating the input of multiple teams of experts into the final versions, it became clear that a systematic support would better suit the long term maintenance of the data specifications, as opposed to solely manual effort.

SEMIC data specifications are published as HTML pages to be consulted by the experts when building their data models. More than that, SEMIC has injected the publication workflow with the ability to coherently generate models with explicit semantics.

For the reason that every manifestation, HTML or semantic models, is sequentially processed from components that operate atomic transformation, SEMIC names this support as “Toolchain”.

The expected benefits of applying a systematic support to data specifications lifecycle are:

1. Harmonised and coherent experience of the browsing data specifications, which in turn seeks to increase the adoption
2. Promotion of SEMIC data modelling best practices, embedding them in the publication workflows
3. Support to scaling up of the editorial capacity through automation.

Introduction

This manual describes the tooling that is supporting the editorial workflow for managing data specifications. It provides a hands-on guide on how to start reusing the SEMIC toolchain and how editors can use it to generate data specification artefacts.

The target audience for this manual:

1. Editors operating or extending an existing SEMIC data specification;
2. Any user who wishes to customise the SEMIC publication process to create new data specifications.

Roles, Tasks, Use Cases, Repositories and Tools

The publication process of a data specification involves 2 roles:

• An editor managing the data specification within its model, metadata, layout and styling
• A toolchain developer in charge to setup the publication environment and processes

During the publication process, multiple tasks are performed covering different tasks executed over one or more use cases:

Task	Use cases
Extend an existing data model	UC1
Updating the UML data model	UC2
Managing Persistent URIs	UC3
Editing HTML specifications	UC4, UC5, UC6
Deploy new software releases	UC7
Customise the publication process	UC8, UC9, UC10, UC11

The Toolchain presented in this manual relies on a set of Github repositories, and are presented in the below table:

Repository	Description
SEMIC thema	This repository mainly contains: EAP files, to be opened by Enterprise Architect to change the data models The template folder, including templates, per language, to change the specific layout of HTML specification Site-skeleton folder, including the screenshot of each data model and the logo, to be include in the HTML specification The config folder, including the JSON configuration file per data model to change various parameters for the publication process
SEMIC publication	This repository mainly contains: The template folder, including generic template that can be reused and customised by the template in the SEMIC thema repository The config folder, including the main JSON publication file under the config/dev folder .circleci folder, including the configuration file of the CircleCI pipeline
SEMIC generated	This repository mainly contains: The report folder which contains the logs of the execution of the CircleCI pipeline The doc folder, which contains the artefacts generated for each specification including the HTML specification, JSON-LD context, SHACL shapes and XSD
SEMIC puri	This repository mainly contains: The release folder which contains, for each namespace, the RDF associated the respective URI
SEMIC proxy	This repository mainly contains: The configurations for the PURI service, in particular the htmlmap.lua which perform the HTML redirection

In the below table the reader can find a summary of the repositories used, the roles involved and the tools needed per use case:

Repositories	UC1	UC2	UC3	UC4	UC5	UC6	UC7	UC8	UC9	UC10	UC11
SEMIC thema	X	X		X	X	X				X
SEMIC publication	X	X		X	X	X	X	X	X	X	X
SEMIC generated	X	X		X	X	X	X	X	X		X
SEMIC puri			X
SEMIC proxy			X
Roles
Editor	X	X	X	X	X	X			X
Toolchain developer			X				X	X	X	X	X
Tools
Git client	X	X	X	X	X	X	X	X	X	X	X
Text editor	X	X	X	X	X	X	X	X	X	X	X
Web browser		X	X	X	X	X	X	X	X	X
Enterprise Architect		X
HTTP client			X
SSH client			X
Public / Private key generator										X
Linux Terminal			X
DockerHub							X
CircleCI							X	X	X	X

As can be seen, most of the time the editor will use mainly the SEMIC thema, publication and generated repository for its operations. The editor and toolchain developer collaborate on UC3 to create and enable persistent URI’s and in UC9 to create a new SEMIC thema repository.