Versioning

Introduction

The Versions page, accessible through the versioning option in the Global Data Management menu, allows sealing (immutable) versions of the dataset being edited, switching to previously sealed versions, as well as forking into new editable branches from them.

The panel lists all versions associated with a dataset, as well as any editable branch. The latter are stored in editable project shards and are modeled as mutable dataset realizations, which accordingly have a temporary version number, usually ending with the suffix -SNAPSHOT. From an editable branch, it is possible to seal a version, which can be archived through a deployer or associated with a new (non-editable) shard of the project to make it browsable.

Editable branches are marked with a pencil; the main branch is also provided with this additional mark. Versions, which are non-editable, are marked with a padlock.

Under each version, there is a list of distributions, whose icons differentiate between browsable and archived . The key difference between these is that distributions of the former type are actually deployed inside VocBench, and thus can be browsed and, in the case of editable branches, edited.

Versions storage configuration

Before sealing a version, a project administrator must provide the necessary storage configurations. To do so, they can click the gear button in the heading of the versions panel.

This opens the versions storage configuration dialog shown below.

Versions storage configuration creation

The versions storage configuration dialog is divided into two side-by-side sections, dedicated to managing the configurations for browsable and archived versions, respectively.

By clicking the "+" button in the header of each section, it is possible to open the dialog for creating a new storage configuration of the appropriate kind.

For browsable versions, the configuration includes the configuration for the repository backing the project shard that will contain the browsable version. The repository configuration is complemented by metadata such as title and description in multiple languages. The overall configuration is assigned an ID to identify it, and its scope can be PROJECT (thus accessible only within the current project) or SYSTEM (accessible system‑wide by any project).

The configuration for archived versions is more complex, as the details vary depending on the type of deployment, which can be "Save to file", "Deploy to triple store", or "Use custom deployer". The key difference lies in whether they require configuring only a reformatting exporter, a deployer, or both a reformatting exporter and a deployer. These aspects have been thoroughly discussed in the section on data export.

The figure below illustrates a configuration for deploying the version into a Turtle file hosted on the VocBench backend.

Create configuration for deployment to locally hosted Turtle file

The figure below illustrates, instead, the configuration for deploying a version into a Turtle file stored on an SFTP server.

Create configuration for deployment to Turtle file stored on SFTP

As can be seen, the configuration of the reformatting exporter is accompanied by the configuration of a deployer, specifically the one capable of storing the file on an SFTP server. Below is the configuration of the latter (which can be edited by clicking the Configure button).

SFTP Deployer configuration with parameters

The configuration properties marked with a "P" inside a circle are parameters: these are never required when preparing the configuration for an extension, since they are later prompted to the user who invokes that specific instance of the extension. However, they can be stored within the configuration, and the provided value will be used as the default for the user prompt.

The example also illustrates the use of the placeholder ${version}, which will be replaced with the actual version identifier when sealing a version.

Versions storage configuration management

Each version storage configuration is associated with a dropdown menu that allows users with suitable rights (project administrators and administrators, the latter in the case of system‑scoped configurations) to edit and delete a configuration.

All configurations stored within the current project and system‑wide can be selected when sealing a version (or when loading an archived version into a project shard), unless they are hidden (by clicking the checkbox at the bottom of the configuration card). Conversely, the radio button can be selected to designate a configuration as the default, which will be used if the user does not explicitly select a configuration.

Sealing a new version

Starting from an editable branch, it is possible to seal a new version with a definite version identifier. The dropdown menu in the header of the versions panel provides two options for consolidating a browsable version or an archived version.

A dialog will prompt the user to choose the desired configuration (among the enabled ones), possibly with a default selection, and to enter the actual values for the parameters defined in that configuration. It also allows changing the value of the current editable branch.

The example below illustrates the case of a deployment to a file on an SFTP server, which only has one parameter: the destination file. However, the user does not need to provide a value, since (as explained earlier) this configuration includes a default for it.

Actions on version distributions

Each version distribution is associated with a dropdown menu that provides access to different actions depending on its nature.

Browsable version

Switch to this version: selects this distribution as the source of the data displayed in VocBench
Fork into editable branch: spawns a new editable branch from this version
Create a new distribution: analogous to sealing an archived version, but aimed at storing a new distribution for an already existing version
Delete

Archived version

Create browsable version: analogous to sealing a browsable version, but starting from an archived (non-browsable) version
Fork into editable branch: spawns a new editable branch from this version
Download
Delete

Forking into an editable branch

Starting from a version, regardless of whether it is browsable or archived, it is possible to fork it into a new editable branch. This action will prompt a dialog analogous to the one used for creating a browsable version from an archived one.

Editable branches work much like the main shard, but with some limitations, such as the absence of history and validation, even if these are enabled for the main project. The only action associated with them in the versions panel is switching to them. If an editable fork is selected, sealing operations work as usual to consolidate the fork into a version.

Notes on creating a browsable version or an editable branch from an archived version

When the user asks to create a new browsable version or an editable branch from an archived version, the data must be loaded back from the deployment destination. This requires a loader that performs the inverse operation of the deployer used when consolidating the version. In fact, this should not be configured explicitly, because VocBench relies on annotations in the deployer configuration to determine:

the appropriate loader
the appropriate configuration type
the appropriate configuration property values

So, for example, when asked to load a version deployed on an SFTP server, VocBench first retrieves the configuration that was used for the deployment and computes its inverse, determining that it can use the SFTP loader with configuration properties automatically deduced from those used at deployment time.